API documentation
BrightGatePay lets your website accept the USDT and USDC stablecoins on TRON, BNB Smart Chain, Ethereum, Polygon, Arbitrum and Base. Customers pay straight into your own wallet. The API creates a payment with an exact amount to send, watches the blockchain, and tells your server when the money has arrived.
Base URL: http://localhost:3000. All bodies are JSON. All times are ISO 8601 in UTC.
Quick start
- Create an account and confirm your email.
- In Payout wallets, add the public address where you want to be paid, for each network you will accept.
- In API keys, create a key. You get an API key, an API secret and a webhook secret. The two secrets are shown once.
- Create a payment from your server, send the customer to its
checkoutUrl, and credit the order when you receive thepayment.paidwebhook.
Keep the secrets on your server only. Never put them in browser or mobile-app code.
Signing requests
Every API request carries three headers:
X-BGP-Site: <your API key>
X-BGP-Timestamp: <unix time in seconds>
X-BGP-Signature: hex( HMAC-SHA256( apiSecret, timestamp + "." + rawBody ) )rawBodyis the exact body you send. ForGETrequests it is the empty string, so you signtimestamp + ".".- The timestamp must be within 5 minutes of the real time. Keep your server clock synchronized.
- A missing or wrong signature, a disabled key or a suspended account all answer
401.
Node.js
import { createHmac } from "node:crypto";
export async function bgp(method, path, body) {
const raw = body === undefined ? "" : JSON.stringify(body);
const ts = Math.floor(Date.now() / 1000).toString();
const sig = createHmac("sha256", process.env.BGP_API_SECRET).update(ts + "." + raw).digest("hex");
const res = await fetch("http://localhost:3000" + path, {
method,
headers: {
"content-type": "application/json",
"X-BGP-Site": process.env.BGP_API_KEY,
"X-BGP-Timestamp": ts,
"X-BGP-Signature": sig,
},
body: method === "GET" ? undefined : raw,
});
const json = await res.json();
if (!res.ok) throw new Error(`BGP ${res.status} ${json.error?.code}: ${json.error?.message}`);
return json;
}PHP
function bgp(string $method, string $path, ?array $body = null): array {
$raw = $body === null ? '' : json_encode($body);
$ts = (string) time();
$sig = hash_hmac('sha256', $ts . '.' . $raw, getenv('BGP_API_SECRET'));
$ch = curl_init('http://localhost:3000' . $path);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => $method === 'GET' ? null : $raw,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-BGP-Site: ' . getenv('BGP_API_KEY'),
'X-BGP-Timestamp: ' . $ts,
'X-BGP-Signature: ' . $sig,
],
]);
$json = json_decode(curl_exec($ch), true);
curl_close($ch);
return $json;
}Python
import hashlib, hmac, json, os, time, requests
def bgp(method, path, body=None):
raw = "" if body is None else json.dumps(body, separators=(",", ":"))
ts = str(int(time.time()))
sig = hmac.new(os.environ["BGP_API_SECRET"].encode(), f"{ts}.{raw}".encode(), hashlib.sha256).hexdigest()
res = requests.request(method, "http://localhost:3000" + path, data=raw or None, headers={
"Content-Type": "application/json",
"X-BGP-Site": os.environ["BGP_API_KEY"],
"X-BGP-Timestamp": ts,
"X-BGP-Signature": sig,
})
return res.json()Create a payment
POST /api/v1/payments
{
"reference": "order_1042",
"network": "usdt-trc20",
"amountUsd": "25.00",
"expiresInMin": 30,
"successUrl": "https://shop.example.com/orders/1042/thanks",
"cancelUrl": "https://shop.example.com/cart",
"metadata": { "plan": "pro" }
}| Field | Rules |
|---|---|
reference | Required. Your own order id, unique per API key, 1–128 characters of A-Z a-z 0-9 _ - : . # /. It makes the call idempotent: sending the same reference again returns the same payment with 200. |
network | Which coin on which chain, e.g. usdt-trc20 or usdc-base (full list under Networks). You need a payout wallet for that chain. |
amountUsd | Required. String or number, at most 2 decimals, from 1.00 to 10000.00. |
expiresInMin | Optional. 5 to 1440 minutes, default 30. |
successUrl, cancelUrl | Optional. Where the hosted checkout page sends the customer afterwards (http or https, up to 500 characters). |
metadata | Optional JSON object up to 4 KB, returned unchanged. Do not put personal data in it. |
Response 201 (or 200 for an existing reference):
{
"id": "pay_8k2m4x7q9c1e3g5j0n6r",
"reference": "order_1042",
"network": "usdt-trc20",
"tokenContract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"address": "T...your payout wallet...",
"amountUsd": "25.00",
"payAmount": "25.0042",
"status": "awaiting",
"receivedAmount": "0.00",
"confirmations": 0,
"txHashes": [],
"deposits": [],
"metadata": { "plan": "pro" },
"checkoutUrl": "http://localhost:3000/pay/pay_8k2m4x7q9c1e3g5j0n6r",
"successUrl": "https://shop.example.com/orders/1042/thanks",
"cancelUrl": "https://shop.example.com/cart",
"expiresAt": "2026-11-18T10:30:00.000Z",
"paidAt": null,
"createdAt": "2026-11-18T10:00:00.000Z",
"updatedAt": "2026-11-18T10:00:00.000Z"
}payAmount is what the customer must send, exactly, with all 4 decimals. It is your price plus a tiny unique suffix (at most 0.0099 USDT). Many payments share one wallet address, and those last digits are what tell them apart. If you build your own payment screen instead of using checkoutUrl, show payAmount, address and the network clearly, and tell the customer to send one transfer of exactly that amount.
Hosted checkout page
Every payment has a ready-made page at checkoutUrl. It shows the amount, your wallet address, a QR code, a countdown and the live status, and sends the customer to your successUrl once the payment is complete. Redirect the customer there, open it in a new tab, or put it in an email or chat message.
Anyone with the link can see that payment's amount, address and status (and nothing else), so treat it like an invoice link. You can also create payment links by hand under Payments in the dashboard, without writing code.
The customer returning to successUrl is not proof of payment. Always rely on the webhook or on a signed GET of the payment.
Get, find and cancel
| Request | What it does |
|---|---|
GET /api/v1/payments/{id} | Returns the payment (same shape as above). |
GET /api/v1/payments?reference=order_1042 | Finds the payment by your reference. |
POST /api/v1/payments/{id}/cancel | Cancels an awaiting or expired payment. The body must be {"id": "<the same payment id>"}. |
Reading an open payment also triggers a blockchain check (at most once every 10 seconds), so polling every 3 to 5 seconds while your customer is on the payment screen gives a fast result. A cancelled or expired payment can still be completed by a transfer that arrives within 24 hours: you would then receive payment.paid, so handle that case.
Networks
GET /api/v1/networks lists the networks available right now and whether you have a payout wallet for each (ready). Offer your customers only the ones with ready: true, and let them choose: each payment is for one network.
| network | Coin | Chain | Token contract | Decimals | Typical time to paid |
|---|---|---|---|---|---|
usdt-bep20 | USDT | BNB Smart Chain (BEP20) | 0x55d398326f99059ff775485246999027b3197955 | 18 | a few seconds |
usdc-bep20 | USDC | BNB Smart Chain (BEP20) | 0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d | 18 | a few seconds |
usdt-trc20 | USDT | TRON (TRC20) | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 | about 1 minute |
usdt-erc20 | USDT | Ethereum (ERC20) | 0xdac17f958d2ee523a2206206994597c13d831ec7 | 6 | about 3 minutes |
usdc-erc20 | USDC | Ethereum (ERC20) | 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 | 6 | about 3 minutes |
usdt-polygon | USDT | Polygon | 0xc2132d05d31c914a87c6611c10748aeb04b58e8f | 6 | about 10 seconds |
usdc-polygon | USDC | Polygon | 0x3c499c542cef5e3811e1192ce70d8cc03d5c3359 | 6 | about 10 seconds |
usdt-arbitrum | USDT | Arbitrum One | 0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9 | 6 | about 1.5 minutes |
usdc-arbitrum | USDC | Arbitrum One | 0xaf88d065e77c8cc2239327c5edb3a432268e5831 | 6 | about 1.5 minutes |
usdc-base | USDC | Base | 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 | 6 | about 2 minutes |
Addresses are 0x… (42 characters) on every network except TRON, where they are T… (34 characters, case-sensitive). In txHashes, TRON transaction ids carry a 0x prefix: drop it to build a Tronscan link. Whatever the token's own decimals, payAmount always has 4.
A transfer sent on a different network, or in a different coin, than the payment's is never seen. Make both obvious to your customer. To let a customer switch, cancel the payment and create a new one with a new reference.
Payment statuses
| Status | Meaning | What you should do |
|---|---|---|
awaiting | Waiting for the transfer. | Keep showing the payment screen. |
confirming | Transfer seen, not final on the blockchain yet. | Show “confirming”. Do not deliver yet. |
paid | The exact amount arrived and is final. | Deliver the order (credit amountUsd). |
underpaid | Less than payAmount arrived and is final. | Decide yourself: credit receivedAmount, or ask for the difference. |
expired | Nothing arrived before expiresAt. | Close the order. A late transfer can still complete it within 24 hours. |
cancelled | You cancelled it. | Same as expired. |
review | A transfer was matched to this payment by hand. | Credit receivedAmount, or apply your own rule. |
paid, underpaid and review are final. Credit an order once, and make it idempotent by payment id. A transfer is matched as underpaid only when exactly one open payment on your wallet is short by no more than 2 USDT or 10% (whichever is larger). Over-payments and transfers that match no payment are not assigned automatically; contact support with the transaction id.
Webhooks
If your API key has a webhook URL, we POST a signed event to it on every status change:
X-BGP-Site: <your API key>
X-BGP-Event-Id: evt_... (the same value on every retry)
X-BGP-Timestamp: <unix time in seconds>
X-BGP-Signature: hex( HMAC-SHA256( webhookSecret, timestamp + "." + rawBody ) )
{
"eventId": "evt_...",
"type": "payment.paid",
"sequence": 3,
"createdAt": "2026-11-18T10:03:12.000Z",
"payment": { "id": "pay_...", "reference": "order_1042", "status": "paid", "receivedAmount": "25.0042", ... }
}Event types: payment.confirming, payment.paid, payment.underpaid, payment.expired, payment.cancelled, payment.review, and rarely payment.awaiting (a transfer that was not final yet disappeared from the blockchain).
- The URL must be
httpson a public host. Redirects are not followed. - Verify the signature over the raw request body with a constant-time comparison, and reject timestamps older than 5 minutes.
- Answer with any
2xxstatus within 10 seconds. Otherwise we retry: 10 attempts over about 22 hours (after 1, 5, 15 and 30 minutes, then 1, 2, 4, 6 and 8 hours). - Use
eventIdto ignore duplicates. Events can arrive out of order: ignore one whosesequenceis lower than the last you handled for that payment, or simply fetch the payment and act on its current status.
import { createHmac, timingSafeEqual } from "node:crypto";
export async function POST(req) {
const raw = await req.text();
const ts = req.headers.get("x-bgp-timestamp") ?? "";
const sig = req.headers.get("x-bgp-signature") ?? "";
const expected = createHmac("sha256", process.env.BGP_WEBHOOK_SECRET).update(ts + "." + raw).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
const ok = fresh && sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
if (!ok) return new Response("bad signature", { status: 401 });
const event = JSON.parse(raw);
if (event.type === "payment.paid") {
// mark order event.payment.reference as paid, once (idempotent by event.payment.id)
}
return new Response("ok");
}Errors and limits
Errors look like { "error": { "code": "invalid_amount", "message": "…" } }.
| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_json, invalid_request, invalid_amount, unsupported_network, metadata_too_large | The request is malformed. The message says which field. |
| 401 | unauthorized | Bad signature or timestamp, unknown or disabled key, suspended account. |
| 404 | not_found | No such payment for this API key. |
| 409 | reference_conflict, not_cancellable | The reference was already used with another amount or network; or the payment can no longer be cancelled. |
| 422 | amount_too_small, amount_too_large, no_address, network_disabled | Outside the allowed amounts, or you have no payout wallet for that network. |
| 429 | rate_limited | More than 120 requests per minute for this key. Wait for Retry-After seconds. |
| 503 | amount_pool_exhausted, allocation_failed | More than 99 open payments with the same USD amount on one wallet. Retry later or change the amount by a cent. |
Questions or a payment that was not matched? Contact support with the payment id or the transaction id.