ilrwebservices / cardpointe-gateway-rest-api-client
PHP library for the CardPointe Gateway API
Requires
- php: >=7.4.0
- ext-json: *
- guzzlehttp/guzzle: >=6.0
README
A simple PHP http client for the CardPointe Gateway REST API. Optimized for JSON and authentication via username and password. Based on Guzzle.
CardPointeGatewayRestClient
is an extended GuzzleHttp\Client
, so it can do all the things that Guzzle can and a bit more.
Be sure to refer to the CardPointe Gateway API documentation for details.
Installation
Via composer:
composer require ilrwebservices/cardpointe-gateway-rest-api-client
Usage
<?php require __DIR__ . '/../vendor/autoload.php'; use CardPointeGateway\CardPointeGatewayRestClient; $client = new CardPointeGatewayRestClient([ 'cp_user' => $_ENV['CARDPOINTE_GATEWAY_API_USER'], 'cp_pass' => $_ENV['CARDPOINTE_GATEWAY_API_PASS'], 'cp_site' => 'fts', ]);
Note how these settings are passed into the client constructor options along with other Guzzle-compatible options. In this example, some sensitive settings are stored in environment variables since they should not be stored in code.
The CardPointeGatewayRestClient
will set the base_uri
option to https://<cp_site>.cardconnect.com/cardconnect/rest/
automatically.
You can now make API calls just as you would in Guzzle:
$client_response = $client->request('GET', 'https://<cp_site>.cardconnect.com/cardconnect/rest/inquireMerchant/<merchid>');
Since the base_uri
option is pre-configured, you can use a relative URL (be sure not to add a leading /
, though):
$client_response = $client->request('GET', 'inquireMerchant/<merchid>');
And because it's Guzzle, there are shorthand methods:
$client_response = $client->get('inquireMerchant/<merchid>');
Responses are PSR-7 response messages, just like Guzzle, so you can get returned data via getBody()
:
$client_data_raw = (string) $client_response->getBody(); // Returns: // { // "site": "fts", // "acctupdater": "N", // "cvv": "N", // "cardproc": "RPCT", // "fee_type": "N", // "enabled": true, // "echeck": "N", // "merchid": "xxxxxxxxxxxx", // "avs": "N" // }
For application/json
responses, CardPointeGatewayRestClient
adds a non-standard getData()
method that decodes the JSON response for you:
$client_data = $client_response->getData(); // Returns: // Array // ( // [site] => fts // [acctupdater] => N // [cvv] => N // [cardproc] => RPCT // [fee_type] => N // [enabled] => 1 // [echeck] => N // [merchid] => xxxxxxxxxxxx // [avs] => N // )
Be careful with large responses, however, as they can consume too much memory.
Sending JSON data to API endpoints can be done using the json
request option from Guzzle:
$new_client_response = $client->post('auth', [ 'json' => [ 'merchid' => 'xxxxxxxxxxxx', 'amount' => '20.01', 'expiry' => 'MMYY', 'account' => '4111111111111111', 'cvv2' => '123', ], ]);
Error handling
You can use Guzzle exceptions for error handling. CardPointe Gateway API endpoints generally use 4xx codes for errors, so GuzzleHttp\Exception\ClientException
is a good match for catching those errors.
try { $new_client_response = $client->post('auth', [ 'json' => [ 'merchid': 'xxxxxxxxxxxx', 'amount': '20.01', 'expiry': 'MMYY', 'account': '4111111111111111', 'cvv2': '123', ], ]); } // Could not connect to server or other network issue. catch (\GuzzleHttp\Exception\ConnectException $e) { print_r($e->getMessage()); } // 4xx error. This is either a 400 Bad Request (e.g. invalid syntax) or // 401 Unauthorized (e.g. bad credentials). catch (\GuzzleHttp\Exception\ClientException $e) { print_r($e->getResponse()->getData()); print_r($e->getMessage()); } // 5xx error. This is an 'Internal Server Error'. catch (\GuzzleHttp\Exception\ServerException $e) { print_r($e->getResponse()->getData()); print_r($e->getMessage()); }
Inspired by drewm/mailchimp-api.