PHP SDK
The official gtrade/payments library for PHP 7.4 and later. Works with Composer or with a plain require, using cURL or PHP streams.
#Install
Download gtrade-payments-php-1.0.0.zip and verify it against the checksums.
The zip contains one folder, gtrade-payments-php/.
With Composer, unzip it into your project (for example into lib/) and add it as a path repository. Run this in the folder that contains your composer.json:
curl -fsSLO https://docs.gtradegateway.io/sdk/gtrade-payments-php-1.0.0.zip
mkdir -p lib && unzip -q gtrade-payments-php-1.0.0.zip -d lib
composer config repositories.gtrade path lib/gtrade-payments-php
composer require gtrade/payments:^1.0Then load Composer's autoloader as usual: require __DIR__ . '/vendor/autoload.php';.
Without Composer, unzip it and include the bundled autoloader:
<?php
require __DIR__ . '/lib/gtrade-payments-php/autoload.php';The examples on this site use the Composer autoloader (vendor/autoload.php). With the plain install, replace that line with the one above.
#Configure
<?php
require __DIR__ . '/vendor/autoload.php';
$gtrade = new \Gtrade\Client(getenv('GTRADE_API_KEY'), [
'base_url' => 'https://api.gtradegateway.io', // API base URL
'timeout' => 30, // seconds per request, default 30
'max_retries' => 2, // retries on 429, 5xx and network errors, default 2
]);
echo $gtrade->getBaseUrl(), PHP_EOL;#Create a payment
<?php
require __DIR__ . '/vendor/autoload.php';
$gtrade = new \Gtrade\Client(getenv('GTRADE_API_KEY'), ['base_url' => 'https://api.gtradegateway.io']);
$payment = $gtrade->payments->create([
'amount_usd' => 25,
'customer_email' => '[email protected]',
'customer_id' => 'cust_1042', // optional
'metadata' => ['order_id' => 'ORD-1042'], // optional
'idempotency_key' => 'order-ORD-1042', // optional, recommended
]);
echo $payment->id, ' ', $payment->status, ' ', $payment->checkout_url, PHP_EOL;Results are \Gtrade\GtradeObject instances: read fields as properties ($payment->checkout_url) or array keys ($payment['checkout_url']), or call toArray().
#Retrieve and list payments
<?php
require __DIR__ . '/vendor/autoload.php';
$gtrade = new \Gtrade\Client(getenv('GTRADE_API_KEY'), ['base_url' => 'https://api.gtradegateway.io']);
$payment = $gtrade->payments->retrieve('9f439f25-f403-446c-9c6a-ecd4aab265e3');
echo $payment->status, ' ', $payment->amount_paid_usd, PHP_EOL;
// One page
$page = $gtrade->payments->list(['limit' => 10, 'status' => 'open']);
echo count($page->data), ' ', var_export($page->has_more, true), PHP_EOL;
// Next page
if ($page->has_more) {
$last = $page->data[count($page->data) - 1];
$next = $gtrade->payments->list(['limit' => 10, 'status' => 'open', 'starting_after' => $last->id]);
echo count($next->data), PHP_EOL;
}
// Every payment, page by page
$count = 0;
foreach ($gtrade->payments->listAutoPaging(['limit' => 100]) as $p) {
$count++;
}
echo 'payments: ', $count, PHP_EOL;#Webhooks
Manage endpoints:
<?php
require __DIR__ . '/vendor/autoload.php';
$gtrade = new \Gtrade\Client(getenv('GTRADE_API_KEY'), ['base_url' => 'https://api.gtradegateway.io']);
$endpoint = $gtrade->webhooks->create('https://shop.example.com/webhooks/gtrade');
$delivery = $gtrade->webhooks->test($endpoint->id);
echo 'test delivery: ', $delivery->status, ' ', var_export($delivery->response_status, true), PHP_EOL;
foreach ($gtrade->webhooks->list()->data as $w) {
echo 'endpoint: ', $w->url, PHP_EOL;
}
$gtrade->webhooks->delete($endpoint->id);Verify incoming events with the raw body (file_get_contents('php://input'); in Laravel, $request->getContent()):
<?php
require __DIR__ . '/vendor/autoload.php';
use Gtrade\Exception\SignatureVerificationError;
use Gtrade\Webhook;
try {
$event = Webhook::constructEvent(
file_get_contents('php://input'),
$_SERVER['HTTP_X_GTRADE_SIGNATURE'] ?? null,
getenv('GTRADE_API_KEY')
);
} catch (SignatureVerificationError $e) {
http_response_code(400);
exit('invalid signature');
}
switch ($event->type) {
case 'payment.paid':
error_log('Paid: ' . $event->data->id); // fulfil the order
break;
case 'payment.cancelled':
error_log('Cancelled: ' . $event->data->id); // release the order
break;
default:
error_log('Event: ' . $event->type . ' ' . $event->data->status);
}
http_response_code(200);
echo 'ok';Webhook::verify($rawBody, $signatureHeader, $apiKey) returns true or false if you only need the check.
#Errors
All exceptions extend \Gtrade\Exception\GtradeError and expose getStatusCode(), getErrorType(), getErrorCode() and getRequestId():
<?php
require __DIR__ . '/vendor/autoload.php';
use Gtrade\Exception\GtradeError;
use Gtrade\Exception\RateLimitError;
use Gtrade\Exception\ValidationError;
$gtrade = new \Gtrade\Client(getenv('GTRADE_API_KEY'), ['base_url' => 'https://api.gtradegateway.io']);
try {
$gtrade->payments->create(['amount_usd' => -5, 'customer_email' => '[email protected]']);
} catch (ValidationError $e) {
echo 'Invalid request: ', $e->getErrorCode(), ' ', $e->getMessage(), PHP_EOL;
} catch (RateLimitError $e) {
echo 'Slow down, retry after ', $e->getRetryAfter(), ' seconds', PHP_EOL;
} catch (GtradeError $e) {
echo 'API error ', $e->getStatusCode(), ' ', $e->getErrorCode(), ' request ', $e->getRequestId(), PHP_EOL;
}Class (\Gtrade\Exception\…) | When |
|---|---|
AuthenticationError | 401: missing or invalid API key. |
NotFoundError | 404: unknown payment, webhook or route. |
ConflictError | 409: idempotency key reused or in use. |
ValidationError | 400, 422: invalid parameters. |
RateLimitError | 429, with getRetryAfter() in seconds. |
ApiError | 5xx and any other status. |
ConnectionError | Network failure or timeout. |
SignatureVerificationError | Webhook::constructEvent with a wrong or missing signature. |