Quickstart
Take your first crypto payment in five minutes. You need a GTRADE merchant account and a terminal.
#1. Get your API key
- Sign in to the GTRADE dashboard.
- Open Developers → API Keys and create a key. Copy it right away and store it in a secret manager or environment variable.
- In your terminal, make it available to the examples on this site:
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
curl https://api.gtradegateway.io/v1/health{"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"
}'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.id, payment.status, 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.id, payment.status, 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->id, ' ', $payment->status, ' ', $payment->checkout_url, PHP_EOL;The response is a Payment object with status open (HTTP 201):
{
"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.paidevent when the payment completes. See Webhooks. - Polling. Retrieve the payment until its
statusispaid:
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, payment.amount_paid_usd));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)<?php
require __DIR__ . '/vendor/autoload.php';
$gtrade = new \Gtrade\Client(getenv('GTRADE_API_KEY'), ['base_url' => 'https://api.gtradegateway.io']);
$payment = $gtrade->payments->retrieve('9f439f25-f403-446c-9c6a-ecd4aab265e3');
echo $payment->status, ' ', $payment->amount_paid_usd, PHP_EOL;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
- Read about payment statuses and what to do for each.
- Set up webhooks and verify their signatures.
- Use an SDK for retries, idempotency and webhook verification out of the box.
- Work through the go-live checklist.