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
| Field | Type | Required | Description |
|---|---|---|---|
amount_usd | number | yes | Amount to charge in USD. Must be greater than 0 and at most 1000000. Send a JSON number, not a string. |
customer_email | string | yes | Your customer's email address (max 254 characters). |
customer_id | string | no | Your own id for the customer (max 128 characters). Defaults to customer_email when omitted. |
metadata | object | no | Your own key-value data, returned on the payment and in every webhook. Max 50 keys and 8 KB as JSON. See Metadata. |
idempotency_key | string | no | Makes 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" }
}'const { Gtrade } = require('gtrade-payments');
const gtrade = new Gtrade({ apiKey: process.env.GTRADE_API_KEY, baseUrl: 'https://api.gtradegateway.io' });
async function main() {
const payment = await gtrade.payments.create({
amountUsd: 25,
customerEmail: '[email protected]',
customerId: 'cust_1042',
metadata: { order_id: 'ORD-1042' },
idempotencyKey: 'order-ORD-1042',
});
console.log(payment.checkout_url);
}
main();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",
metadata={"order_id": "ORD-1042"},
idempotency_key="order-ORD-1042",
)
print(payment.checkout_url)<?php
require __DIR__ . '/vendor/autoload.php';
$gtrade = new \Gtrade\Client(getenv('GTRADE_API_KEY'), ['base_url' => 'https://api.gtradegateway.io']);
$payment = $gtrade->payments->create([
'amount_usd' => 25,
'customer_email' => '[email protected]',
'customer_id' => 'cust_1042',
'metadata' => ['order_id' => 'ORD-1042'],
'idempotency_key' => 'order-ORD-1042',
]);
echo $payment->checkout_url, PHP_EOL;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:
{
"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
{
"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"
}| Field | Type | Description |
|---|---|---|
id | string | Unique payment id (a UUID). Store it with your order. |
object | string | Always "payment". |
status | string | One of the payment statuses. |
amount_usd | number | The amount requested, in USD. |
amount_paid_usd | number | USD value received so far. 0 until a deposit is detected. |
currency | string or null | Token the customer chose at checkout, for example USDC. null until they choose. |
network | string or null | Blockchain the customer chose, for example BASE or ETH. null until they choose. |
customer_email | string or null | As sent when the payment was created. |
customer_id | string or null | As sent, or the email when no id was sent. |
checkout_url | string | The hosted checkout page for this payment. |
metadata | object | Your metadata. {} when none was set (also for payments created from a dashboard payment link). |
created_at, updated_at | string | ISO-8601 timestamps in UTC. |
#Payment statuses
| Status | Meaning | What to do |
|---|---|---|
open | Waiting for the customer to pay. No deposit seen yet. | Nothing. Keep the order pending. |
pending | A deposit was detected and is waiting for blockchain confirmations. | Show "payment processing". Don't ship yet. |
partially_paid | The customer sent less than the requested amount. | Compare amount_paid_usd with amount_usd. See underpayments. |
paid | The full amount (or more) was received and confirmed. | Fulfil the order. If amount_paid_usd > amount_usd, the customer overpaid. |
cancelled | The 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
curl https://api.gtradegateway.io/v1/payments/9f439f25-f403-446c-9c6a-ecd4aab265e3 \
-H "Authorization: Bearer $GTRADE_API_KEY"const { Gtrade } = require('gtrade-payments');
const gtrade = new Gtrade({ apiKey: process.env.GTRADE_API_KEY, baseUrl: 'https://api.gtradegateway.io' });
gtrade.payments.retrieve('9f439f25-f403-446c-9c6a-ecd4aab265e3')
.then((payment) => console.log(payment.status));import os
from gtrade_payments import Gtrade
gtrade = Gtrade(api_key=os.environ["GTRADE_API_KEY"], base_url="https://api.gtradegateway.io")
print(gtrade.payments.retrieve("9f439f25-f403-446c-9c6a-ecd4aab265e3").status)<?php
require __DIR__ . '/vendor/autoload.php';
$gtrade = new \Gtrade\Client(getenv('GTRADE_API_KEY'), ['base_url' => 'https://api.gtradegateway.io']);
echo $gtrade->payments->retrieve('9f439f25-f403-446c-9c6a-ecd4aab265e3')->status, PHP_EOL;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
Returns your payments, newest first.
| Query parameter | Description |
|---|---|
limit | Page size, 1 to 100. Default 10. |
status | Only payments with this status. |
starting_after | A 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"const { Gtrade } = require('gtrade-payments');
const gtrade = new Gtrade({ apiKey: process.env.GTRADE_API_KEY, baseUrl: 'https://api.gtradegateway.io' });
gtrade.payments.list({ limit: 2 }).then((page) => {
for (const p of page.data) console.log(p.id, p.status, p.amount_usd);
console.log('has_more:', page.has_more);
});import os
from gtrade_payments import Gtrade
gtrade = Gtrade(api_key=os.environ["GTRADE_API_KEY"], base_url="https://api.gtradegateway.io")
page = gtrade.payments.list(limit=2)
for p in page.data:
print(p.id, p.status, p.amount_usd)
print("has_more:", page.has_more)<?php
require __DIR__ . '/vendor/autoload.php';
$gtrade = new \Gtrade\Client(getenv('GTRADE_API_KEY'), ['base_url' => 'https://api.gtradegateway.io']);
$page = $gtrade->payments->list(['limit' => 2]);
foreach ($page->data as $p) {
echo $p->id, ' ', $p->status, ' ', $p->amount_usd, PHP_EOL;
}
echo 'has_more: ', var_export($page->has_more, true), PHP_EOL;{
"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:
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();import os
from gtrade_payments import Gtrade
gtrade = Gtrade(api_key=os.environ["GTRADE_API_KEY"], base_url="https://api.gtradegateway.io")
total = sum(p.amount_paid_usd for p in gtrade.payments.list_auto_paging(status="paid", limit=100))
print("Total received (USD):", total)<?php
require __DIR__ . '/vendor/autoload.php';
$gtrade = new \Gtrade\Client(getenv('GTRADE_API_KEY'), ['base_url' => 'https://api.gtradegateway.io']);
$total = 0;
foreach ($gtrade->payments->listAutoPaging(['status' => 'paid', 'limit' => 100]) as $p) {
$total += $p->amount_paid_usd;
}
echo 'Total received (USD): ', $total, PHP_EOL;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.
| Situation | Result |
|---|---|
| New key | The payment is created: 201. |
| Same key, same parameters | 201 with the original payment in its current state, and the response header Idempotent-Replayed: true. |
| Same key, different parameters | 409 with code idempotency_key_reused. |
| Same key while the first request is still running | 409 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.
{
"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).