GTRADEDocs
Get started

Quickstart

Take your first crypto payment in five minutes. You need a GTRADE merchant account and a terminal.

#1. Get your API key

  1. Sign in to the GTRADE dashboard.
  2. Open Developers → API Keys and create a key. Copy it right away and store it in a secret manager or environment variable.
  3. In your terminal, make it available to the examples on this site:
bash
export GTRADE_API_KEY="your API key"

Warning: Your API key is secret. It authenticates every request and signs your webhooks. Use it only on your server, never in a browser, mobile app or public repository. See Authentication.

#2. Check connectivity

bash
curl https://api.gtradegateway.io/v1/health
json
{"status":"ok"}

#3. Create a payment

Send the amount in USD and your customer's email. Pass your own order id in metadata so you can match the payment later, and an idempotency_key so a retried request never creates a second payment.

curl https://api.gtradegateway.io/v1/payments \
  -H "Authorization: Bearer $GTRADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 25,
    "customer_email": "[email protected]",
    "customer_id": "cust_1042",
    "metadata": { "order_id": "ORD-1042" },
    "idempotency_key": "order-ORD-1042"
  }'

The response is a Payment object with status open (HTTP 201):

json
{
  "id": "9f439f25-f403-446c-9c6a-ecd4aab265e3",
  "object": "payment",
  "status": "open",
  "amount_usd": 25,
  "amount_paid_usd": 0,
  "currency": null,
  "network": null,
  "customer_email": "[email protected]",
  "customer_id": "cust_1042",
  "checkout_url": "https://checkout.gtradegateway.io/payments?reference_id=9f439f25-f403-446c-9c6a-ecd4aab265e3",
  "metadata": { "order_id": "ORD-1042" },
  "created_at": "2026-11-17T16:34:38.052139Z",
  "updated_at": "2026-11-17T16:34:38.052139Z"
}

Tip: Running the same request again with the same idempotency_key returns the same payment (HTTP 201 with the header Idempotent-Replayed: true) instead of creating a new one.

#4. Send the customer to the checkout

Redirect the customer's browser to checkout_url, or show it as a link or button. On the hosted checkout the customer picks a coin and network (for example USDC on Base), sees the exact amount, the deposit address and a QR code, and pays from any wallet or exchange. See Hosted checkout.

#5. Confirm the payment

Your server learns about the result in one of two ways:

  • Webhooks (recommended). Register an HTTPS endpoint once, and GTRADE sends a signed payment.paid event when the payment completes. See Webhooks.
  • Polling. Retrieve the payment until its status is paid:
curl https://api.gtradegateway.io/v1/payments/9f439f25-f403-446c-9c6a-ecd4aab265e3 \
  -H "Authorization: Bearer $GTRADE_API_KEY"

Fulfil the order only when status is paid. A payment that has paid status can have amount_paid_usd above amount_usd if the customer overpaid.

#Next steps