SDKs
Python SDK
The official gtrade_payments package for Python. No runtime dependencies, fully typed.
#Install
pip install https://docs.gtradegateway.io/sdk/gtrade_payments-1.0.0-py3-none-any.whlIn 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
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
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
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:
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:
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", 200Webhook.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:
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)| Class | 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 retry_after in seconds. |
ApiError | 5xx and any other status. |
ConnectionError | Network failure or timeout. |
SignatureVerificationError | Webhook.construct_event with a wrong or missing signature. |