GTRADEDocs
SDKs

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:

bash
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.0

Then load Composer's autoloader as usual: require __DIR__ . '/vendor/autoload.php';.

Without Composer, unzip it and include the bundled autoloader:

php
<?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
<?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
<?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
<?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
<?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
<?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
<?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
AuthenticationError401: missing or invalid API key.
NotFoundError404: unknown payment, webhook or route.
ConflictError409: idempotency key reused or in use.
ValidationError400, 422: invalid parameters.
RateLimitError429, with getRetryAfter() in seconds.
ApiError5xx and any other status.
ConnectionErrorNetwork failure or timeout.
SignatureVerificationErrorWebhook::constructEvent with a wrong or missing signature.