GTRADEDocs
SDKs

Python SDK

The official gtrade_payments package for Python. No runtime dependencies, fully typed.

#Install

bash
pip install https://docs.gtradegateway.io/sdk/gtrade_payments-1.0.0-py3-none-any.whl

In requirements.txt, add the line gtrade-payments @ https://docs.gtradegateway.io/sdk/gtrade_payments-1.0.0-py3-none-any.whl. You can verify the file against the checksums.

#Configure

python
import os
from gtrade_payments import Gtrade

gtrade = Gtrade(
    api_key=os.environ["GTRADE_API_KEY"],  # required
    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
)
print(gtrade.base_url)

#Create a payment

python
import os
from gtrade_payments import Gtrade

gtrade = Gtrade(api_key=os.environ["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
)
print(payment.id, payment.status, payment.checkout_url)

Results are dictionaries that also allow attribute access: payment.checkout_url and payment["checkout_url"] are the same.

#Retrieve and list payments

python
import os
from gtrade_payments import Gtrade

gtrade = Gtrade(api_key=os.environ["GTRADE_API_KEY"], base_url="https://api.gtradegateway.io")

payment = gtrade.payments.retrieve("9f439f25-f403-446c-9c6a-ecd4aab265e3")
print(payment.status, payment.amount_paid_usd)

# One page
page = gtrade.payments.list(limit=10, status="open")
print(len(page.data), page.has_more)

# Next page
if page.has_more:
    nxt = gtrade.payments.list(limit=10, status="open", starting_after=page.data[-1].id)
    print(len(nxt.data))

# Every payment, page by page
count = sum(1 for _ in gtrade.payments.list_auto_paging(limit=100))
print("payments:", count)

#Webhooks

Manage endpoints:

python
import os
from gtrade_payments import Gtrade

gtrade = Gtrade(api_key=os.environ["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)
print("test delivery:", delivery.status, delivery.response_status)
print("endpoints:", [w.url for w in gtrade.webhooks.list().data])
gtrade.webhooks.delete(endpoint.id)

Verify incoming events with the raw body. In Flask that's request.get_data(); in Django, request.body:

python
import os

from flask import Flask, request
from gtrade_payments import SignatureVerificationError, Webhook

app = Flask(__name__)


@app.post("/webhooks/gtrade")
def gtrade_webhook():
    try:
        event = Webhook.construct_event(
            request.get_data(), request.headers.get("X-Gtrade-Signature"), os.environ["GTRADE_API_KEY"]
        )
    except SignatureVerificationError:
        return "invalid signature", 400

    if event.type == "payment.paid":
        print("Paid:", event.data.id, event.data.metadata)  # fulfil the order
    elif event.type == "payment.cancelled":
        print("Cancelled:", event.data.id)  # release the order
    else:
        print("Event:", event.type, event.data.status)
    return "ok", 200

Webhook.verify(raw_body, signature_header, api_key) returns True or False if you only need the check.

#Errors

All errors extend GtradeError and carry status_code, type, code and request_id:

python
import os
from gtrade_payments import Gtrade, GtradeError, RateLimitError, ValidationError

gtrade = Gtrade(api_key=os.environ["GTRADE_API_KEY"], base_url="https://api.gtradegateway.io")

try:
    gtrade.payments.create(amount_usd=-5, customer_email="[email protected]")
except ValidationError as err:
    print("Invalid request:", err.code, err.message)
except RateLimitError as err:
    print("Slow down, retry after", err.retry_after, "seconds")
except GtradeError as err:
    print("API error", err.status_code, err.code, "request", err.request_id)
ClassWhen
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 retry_after in seconds.
ApiError5xx and any other status.
ConnectionErrorNetwork failure or timeout.
SignatureVerificationErrorWebhook.construct_event with a wrong or missing signature.