SDKs
SDKs
Official GTRADE libraries for Node.js, Python and PHP. They handle authentication, retries, idempotency, pagination and webhook signature verification.
#Libraries
| Language | Package | Requirements | Install |
|---|---|---|---|
| Node.js | gtrade-payments | Node.js 18+ (no dependencies) | npm install https://docs.gtradegateway.io/sdk/gtrade-payments-1.0.0.tgz |
| Python | gtrade-payments (import gtrade_payments) | Python 3.8+ (no dependencies) | pip install https://docs.gtradegateway.io/sdk/gtrade_payments-1.0.0-py3-none-any.whl |
| PHP | gtrade/payments | PHP 7.4+ with ext-json (ext-curl recommended) | Download the zip |
#Downloads and checksums
The SDKs are distributed from this site:
| File | Link |
|---|---|
| Node.js package | gtrade-payments-1.0.0.tgz |
| Python wheel | gtrade_payments-1.0.0-py3-none-any.whl |
| PHP library | gtrade-payments-php-1.0.0.zip |
| SHA-256 checksums | SHA256SUMS |
To check a download against the published checksums:
curl -fsSO https://docs.gtradegateway.io/sdk/SHA256SUMS
curl -fsSO https://docs.gtradegateway.io/sdk/gtrade-payments-1.0.0.tgz
sha256sum --check --ignore-missing SHA256SUMSOn macOS use shasum -a 256 --check --ignore-missing SHA256SUMS.
#What every SDK does for you
- Authentication: send your key once in the constructor.
- Base URL: pass
https://api.gtradegateway.ioexplicitly, as in the examples, so a change of default never affects you. - Automatic retries: on
429(honouringRetry-After),5xxand network errors, with exponential backoff (2 retries by default,0disables them). Reads and deletes are retried; creating a payment is retried only with an idempotency key, and the SDK generates one per call when you don't pass yours, so a retry never creates a duplicate. Registering and testing webhook endpoints is never retried automatically. - Typed errors: authentication, not found, conflict (idempotency), validation, rate limit, API and connection errors, each with the HTTP status, error code and
request_id. - Pagination: an auto-paging iterator over
GET /v1/payments. - Webhooks:
verifyandconstructEvent/construct_eventcheckX-Gtrade-Signatureagainst the raw body in constant time.
#Method overview
| Operation | Node.js | Python | PHP |
|---|---|---|---|
| Create payment | payments.create({ amountUsd, customerEmail, … }) | payments.create(amount_usd=…, customer_email=…) | payments->create(['amount_usd' => …, …]) |
| Retrieve payment | payments.retrieve(id) | payments.retrieve(id) | payments->retrieve($id) |
| List payments | payments.list({ limit, status, startingAfter }) | payments.list(limit=…, status=…, starting_after=…) | payments->list(['limit' => …]) |
| Iterate all payments | payments.listAutoPaging(params) | payments.list_auto_paging(…) | payments->listAutoPaging([...]) |
| Register webhook | webhooks.create(url) | webhooks.create(url) | webhooks->create($url) |
| List webhooks | webhooks.list() | webhooks.list() | webhooks->list() |
| Delete webhook | webhooks.delete(id) | webhooks.delete(id) | webhooks->delete($id) |
| Send test event | webhooks.test(id) | webhooks.test(id) | webhooks->test($id) |
| Verify webhook | Webhook.verify(raw, sig, key) | Webhook.verify(raw, sig, key) | \Gtrade\Webhook::verify($raw, $sig, $key) |
| Verify and parse | Webhook.constructEvent(raw, sig, key) | Webhook.construct_event(raw, sig, key) | \Gtrade\Webhook::constructEvent($raw, $sig, $key) |
Responses are the API objects described in this documentation, with the same snake_case field names in every language (payment.checkout_url, payment.amount_paid_usd).
#No SDK for your language?
The API is plain JSON over HTTPS, so any HTTP client works. Follow the cURL examples throughout these docs and the signature verification recipe.