GTRADEDocs
Accept payments

Payments

A Payment is a request for an amount in USD from one customer. Create it on your server, send the customer to its checkout, and track its status.

#Create a payment

POST /v1/payments
FieldTypeRequiredDescription
amount_usdnumberyesAmount to charge in USD. Must be greater than 0 and at most 1000000. Send a JSON number, not a string.
customer_emailstringyesYour customer's email address (max 254 characters).
customer_idstringnoYour own id for the customer (max 128 characters). Defaults to customer_email when omitted.
metadataobjectnoYour own key-value data, returned on the payment and in every webhook. Max 50 keys and 8 KB as JSON. See Metadata.
idempotency_keystringnoMakes the request safe to retry (max 255 characters). You can send it as the Idempotency-Key header instead. See Idempotency.
curl https://api.gtradegateway.io/v1/payments \
  -H "Authorization: Bearer $GTRADE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-ORD-1042" \
  -d '{
    "amount_usd": 25,
    "customer_email": "[email protected]",
    "customer_id": "cust_1042",
    "metadata": { "order_id": "ORD-1042" }
  }'

Returns 201 Created with the Payment. Redirect your customer to its checkout_url.

Validation errors return 422 with code parameter_missing or parameter_invalid and a message naming the field:

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "amount_usd must be a number greater than 0.",
    "request_id": "req_2e9b9768a3515600"
  }
}

#The Payment object

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"
}
FieldTypeDescription
idstringUnique payment id (a UUID). Store it with your order.
objectstringAlways "payment".
statusstringOne of the payment statuses.
amount_usdnumberThe amount requested, in USD.
amount_paid_usdnumberUSD value received so far. 0 until a deposit is detected.
currencystring or nullToken the customer chose at checkout, for example USDC. null until they choose.
networkstring or nullBlockchain the customer chose, for example BASE or ETH. null until they choose.
customer_emailstring or nullAs sent when the payment was created.
customer_idstring or nullAs sent, or the email when no id was sent.
checkout_urlstringThe hosted checkout page for this payment.
metadataobjectYour metadata. {} when none was set (also for payments created from a dashboard payment link).
created_at, updated_atstringISO-8601 timestamps in UTC.

#Payment statuses

StatusMeaningWhat to do
openWaiting for the customer to pay. No deposit seen yet.Nothing. Keep the order pending.
pendingA deposit was detected and is waiting for blockchain confirmations.Show "payment processing". Don't ship yet.
partially_paidThe customer sent less than the requested amount.Compare amount_paid_usd with amount_usd. See underpayments.
paidThe full amount (or more) was received and confirmed.Fulfil the order. If amount_paid_usd > amount_usd, the customer overpaid.
cancelledThe payment can no longer be paid: the checkout link expired, or it was replaced by a newer request.Release the order or create a new payment if the customer still wants to pay.

A typical successful payment goes open → pending → paid. Treat paid as final.

Note: The API also accepts expired as a filter and the SDKs list it as a possible value, reserved for future use. Today an expired checkout link is reported as cancelled, and filtering by status=expired always returns an empty list.

#Retrieve a payment

GET /v1/payments/{id}
curl https://api.gtradegateway.io/v1/payments/9f439f25-f403-446c-9c6a-ecd4aab265e3 \
  -H "Authorization: Bearer $GTRADE_API_KEY"

Returns 200 with the Payment. You can retrieve any payment of your account, including payments created from a dashboard payment link. An unknown id, or a payment that belongs to another account, returns 404 payment_not_found.

#List payments

GET /v1/payments

Returns your payments, newest first.

Query parameterDescription
limitPage size, 1 to 100. Default 10.
statusOnly payments with this status.
starting_afterA payment id from the previous page. Returns the payments that come after it.
curl "https://api.gtradegateway.io/v1/payments?limit=2" \
  -H "Authorization: Bearer $GTRADE_API_KEY"
json
{
  "object": "list",
  "data": [
    { "id": "9f439f25-f403-446c-9c6a-ecd4aab265e3", "object": "payment", "status": "open", "amount_usd": 25, "...": "..." },
    { "id": "dc3d3194-0b7a-4240-8de9-73f73c199a14", "object": "payment", "status": "open", "amount_usd": 2, "...": "..." }
  ],
  "has_more": true
}

#Pagination

Lists use cursor pagination. When has_more is true, request the next page with starting_after set to the id of the last payment in data:

bash
curl "https://api.gtradegateway.io/v1/payments?limit=2&starting_after=9f439f25-f403-446c-9c6a-ecd4aab265e3" \
  -H "Authorization: Bearer $GTRADE_API_KEY"

The SDKs can walk every page for you:

const { Gtrade } = require('gtrade-payments');
const gtrade = new Gtrade({ apiKey: process.env.GTRADE_API_KEY, baseUrl: 'https://api.gtradegateway.io' });

async function main() {
  let total = 0;
  for await (const p of gtrade.payments.listAutoPaging({ status: 'paid', limit: 100 })) {
    total += p.amount_paid_usd;
  }
  console.log('Total received (USD):', total);
}
main();

A limit outside 1–100, an unknown status, or a starting_after id that is not in the list returns 400 parameter_invalid.

#Idempotency

Networks fail. If your request times out, you can't know whether the payment was created. Send an idempotency key (a unique string per order or per attempt, for example order-ORD-1042) and retry with the same key: you will never create a duplicate payment.

Send it as the Idempotency-Key header or the idempotency_key body field. If you send both, they must be equal.

SituationResult
New keyThe payment is created: 201.
Same key, same parameters201 with the original payment in its current state, and the response header Idempotent-Replayed: true.
Same key, different parameters409 with code idempotency_key_reused.
Same key while the first request is still running409 with code idempotency_key_in_use. Wait a moment and retry.

Keys are scoped to your merchant account and do not expire, so don't reuse a key for a different order. "Same parameters" means the same amount_usd, customer_email, customer_id and metadata.

json
{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "This idempotency key was already used with different parameters.",
    "request_id": "req_3ae0621360c5bd5c"
  }
}

Tip: The SDKs retry failed requests automatically. When you don't pass an idempotency key, they generate one per call so that those automatic retries stay safe. Pass your own key (such as your order id) to also make your own retries safe.

#Metadata

Use metadata to attach your own data to a payment, such as your order id, cart id or internal customer reference. GTRADE stores it, never interprets it, and returns it on the payment and in every webhook event.

  • A JSON object with at most 50 keys and 8 KB when serialized.
  • Values can be any JSON type (strings, numbers, booleans, nested objects).
  • Don't store secrets or sensitive personal data in metadata.

#Amounts and currencies

You always price in USD (amount_usd). The customer chooses which supported coin and network to pay with on the checkout, and the checkout shows the exact crypto amount to send. After they choose, currency and network are set on the payment. See the FAQ for supported coins and networks.

amount_paid_usd is the USD value of what was received. It can be lower than amount_usd (partially_paid) or higher (overpayment, still paid).