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

  1. Create an account and confirm your email.
  2. In Payout wallets, add the public address where you want to be paid, for each network you will accept.
  3. In API keys, create a key. You get an API key, an API secret and a webhook secret. The two secrets are shown once.
  4. Create a payment from your server, send the customer to its checkoutUrl, and credit the order when you receive the payment.paid webhook.

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 ) )
  • rawBody is the exact body you send. For GET requests it is the empty string, so you sign timestamp + ".".
  • 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" }
}
FieldRules
referenceRequired. 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.
networkWhich coin on which chain, e.g. usdt-trc20 or usdc-base (full list under Networks). You need a payout wallet for that chain.
amountUsdRequired. String or number, at most 2 decimals, from 1.00 to 10000.00.
expiresInMinOptional. 5 to 1440 minutes, default 30.
successUrl, cancelUrlOptional. Where the hosted checkout page sends the customer afterwards (http or https, up to 500 characters).
metadataOptional 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

RequestWhat it does
GET /api/v1/payments/{id}Returns the payment (same shape as above).
GET /api/v1/payments?reference=order_1042Finds the payment by your reference.
POST /api/v1/payments/{id}/cancelCancels 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.

networkCoinChainToken contractDecimalsTypical time to paid
usdt-bep20USDTBNB Smart Chain (BEP20)0x55d398326f99059ff775485246999027b319795518a few seconds
usdc-bep20USDCBNB Smart Chain (BEP20)0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d18a few seconds
usdt-trc20USDTTRON (TRC20)TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t6about 1 minute
usdt-erc20USDTEthereum (ERC20)0xdac17f958d2ee523a2206206994597c13d831ec76about 3 minutes
usdc-erc20USDCEthereum (ERC20)0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb486about 3 minutes
usdt-polygonUSDTPolygon0xc2132d05d31c914a87c6611c10748aeb04b58e8f6about 10 seconds
usdc-polygonUSDCPolygon0x3c499c542cef5e3811e1192ce70d8cc03d5c33596about 10 seconds
usdt-arbitrumUSDTArbitrum One0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb96about 1.5 minutes
usdc-arbitrumUSDCArbitrum One0xaf88d065e77c8cc2239327c5edb3a432268e58316about 1.5 minutes
usdc-baseUSDCBase0x833589fcd6edb6e08f4c7c32d4f71b54bda029136about 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

StatusMeaningWhat you should do
awaitingWaiting for the transfer.Keep showing the payment screen.
confirmingTransfer seen, not final on the blockchain yet.Show “confirming”. Do not deliver yet.
paidThe exact amount arrived and is final.Deliver the order (credit amountUsd).
underpaidLess than payAmount arrived and is final.Decide yourself: credit receivedAmount, or ask for the difference.
expiredNothing arrived before expiresAt.Close the order. A late transfer can still complete it within 24 hours.
cancelledYou cancelled it.Same as expired.
reviewA 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 https on 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 2xx status 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 eventId to ignore duplicates. Events can arrive out of order: ignore one whose sequence is 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": "…" } }.

HTTPcodeMeaning
400invalid_json, invalid_request, invalid_amount, unsupported_network, metadata_too_largeThe request is malformed. The message says which field.
401unauthorizedBad signature or timestamp, unknown or disabled key, suspended account.
404not_foundNo such payment for this API key.
409reference_conflict, not_cancellableThe reference was already used with another amount or network; or the payment can no longer be cancelled.
422amount_too_small, amount_too_large, no_address, network_disabledOutside the allowed amounts, or you have no payout wallet for that network.
429rate_limitedMore than 120 requests per minute for this key. Wait for Retry-After seconds.
503amount_pool_exhausted, allocation_failedMore 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.