₮ USDT Payment Portal
← Back to Home Merchant Login Register now
API Documentation

Gateway AddressProvides a RESTful API with HMAC-SHA256 signature authentication; invoice payments, deposit payments and Webhook notifications cover the entire payment flow.

1. Overview
Gateway Address
https://pay.example.com (Example domain; see the real address in Credentials)
AppID
(Assigned after approval)
HMAC Key
•••••••••••••••• (Server-side signing only. Keep it safe.) View / Reset
All /v1/* endpoints require signed request headers unless marked Public. Keep the signing key on your server only; never ship it to browsers or clients.
2. Signing

1Build the request body (GET requests have no body; use an empty string).

2Assemble the string to sign: nonce + timestamp + raw request body.

3Compute HMAC-SHA256 with the HMAC Key and take the hex result.

4Send the four headers together with the request.

HeaderDescription
XC-AppidProject AppID
XC-TimestampUnix timestamp in seconds; expired or missing values are rejected
XC-NonceRandom string unique per request; the server uses it for idempotent dedup
XC-SignatureHMAC-SHA256 signature (hex)
Content-Typeapplication/json
POST Request Example
<?php
$appid    = '你的AppID';
$hmacKey  = '你的HMAC_Key';
$apiBase  = 'https://pay.example.com';   // 换成你在「接入凭据」页看到的真实网关地址

$body = json_encode([
    'out_no'   => 'order_' . time(),   // 商户订单号,≤32 位,项目内唯一
    'title'    => '订单标题',
    'currency' => 'USD',               // 计价法币
    'amount'   => '29.99',             // 计价金额(字符串)
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

$timestamp = (string)time();                       // 秒级时间戳
$nonce     = bin2hex(random_bytes(16));            // 每次请求唯一
$signature = hash_hmac('sha256', $nonce . $timestamp . $body, $hmacKey);

$ch = curl_init($apiBase . '/v1/invoice');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'XC-Appid: '     . $appid,
        'XC-Timestamp: ' . $timestamp,
        'XC-Nonce: '     . $nonce,
        'XC-Signature: ' . $signature,
    ],
]);

$result = json_decode(curl_exec($ch), true);
header('Location: ' . $result['pay_url']);         // 跳转到支付页
Signature Numeric Example
Given nonce=a1b2c3, timestamp=1717300000, body {"out_no":"o1","amount":"10"}, the string to sign is a1b2c31717300000{"out_no":"o1","amount":"10"} (concatenated directly, no separator). Compute HMAC-SHA256 with the HMAC Key and take hex — that is XC-Signature. For GET requests the body is an empty string, so the string to sign is nonce + timestamp.
3. Endpoint Overview
MethodPathDescriptionSignature
POST /v1/invoice Create an invoice and get the payment redirect URL Required
GET /v1/invoice/{sys_no} Query the public status of an invoice Public
GET /v1/deposit/address Get the dedicated deposit address for an end customer Required
3.5 Supported Chains & Cryptos

When creating invoices or requesting deposit addresses, you need to specify chain and crypto parameters. The tables below list all supported chains and common cryptos with their API parameter values.

Chains (chain)
NameAPI ParameterTypeGas TokenChain ID
EthereumethereumEVMETH1
BNB Smart ChainbscEVMBNB56
Polygon PoSpolygonEVMPOL137
Arbitrum Onearbitrum-oneEVMETH42161
OptimismoptimismEVMETH10
BasebaseEVMETH8453
TrontronTronTRX-
Cryptos (crypto)
NameAPI ParameterTypeDescription
Tether USDUSDTERC-20 / TRC-20Stablecoin, most common payment crypto
USD CoinUSDCERC-20Stablecoin, available on multiple EVM chains
DaiDAIERC-20Stablecoin
EtherETHNativeNative gas token of Ethereum, Arbitrum, Optimism, Base
BNBBNBNativeNative gas token of BNB Smart Chain
PolygonPOLNativeNative gas token of Polygon PoS
TRONTRXNativeNative gas token of Tron
EVM chains support any ERC-20 token — add the token contract address in the admin panel to enable it. Tron currently supports USDT and native TRX only. Actual available chain/crypto combinations depend on the backend configuration.
4. Create Invoice
POSThttps://pay.example.com/v1/invoice
FieldRequiredDescription
out_noYesMerchant order number, up to 32 chars, unique within the project
titleYesInvoice title, up to 32 chars
currencyYesFiat currency code; supports USD, CNY and other major fiats
amountYesAmount as string, range 0.00000001 ~ 1000000, up to 8 decimals
durationNoValidity in minutes, 5 ~ 30, default 10
methodsNoRestrict payment methods, format {"crypto": ["chain"]}
notify_urlNoInvoice-level callback URL, takes precedence over the project default
return_urlNoSync redirect URL after payment completion
Request Example
{
  "out_no": "order-20260602-001",
  "title": "Premium Plan",
  "currency": "USD",
  "amount": "29.99",
  "duration": 15,
  "methods": { "USDT": ["tron"] },
  "notify_url": "https://你的域名/xcash/webhook",
  "return_url": "https://你的域名/payment/success"
}
Response Example
{
  "appid": "XC-XXXXXXXX",
  "sys_no": "INV2606028X7K2P9Q",
  "out_no": "order-20260602-001",
  "status": "waiting",
  "currency": "USD",
  "amount": "29.99",
  "chain": null,
  "crypto": null,
  "pay_address": null,
  "pay_amount": null,
  "pay_url": "https://pay.example.com/pay/INV2606028X7K2P9Q",
  "started_at": "2026-06-02T12:00:00Z",
  "expires_at": "2026-06-02T12:15:00Z"
}
Key Points
  • currency only determines the pricing unit of amount; the chain and crypto the buyer actually pays with are decided by methods.
  • If methods is omitted, the system builds chain/crypto combinations from the project's current capabilities; if provided, it must be a subset, otherwise a "no available payment method" error is returned.
  • Always use the chain / crypto / pay_address / pay_amount returned by the invoice page or query API as what the buyer should pay; never derive them from amount yourself.
  • The on-chain amount may carry a small adjusted tail (to distinguish invoices sharing one address); paying exactly pay_amount is required for automatic matching.
  • Direct the user to the returned pay_url to complete coin selection and payment.
  • pay_url is valid for the invoice duration (default 10 minutes); after expiry the link is invalid and a new invoice must be created.
5. Query Invoice
GEThttps://pay.example.com/v1/invoice/{sys_no}
  • Public endpoint, no signature required — ideal for frontend polling of payment results.
  • Recommended polling interval: 5 ~ 15 seconds; payment is complete when status is completed (do not rely on confirmed).
  • The invoice becomes expired after expires_at; payment must be completed before that.
  • If return_url was provided when creating the invoice, this field returns a signed sync redirect URL on completion; fulfillment should still rely on the Webhook.
Response Example
{
  "sys_no": "INV2606028X7K2P9Q",
  "out_no": "order-20260602-001",
  "status": "completed",
  "currency": "USD",
  "amount": "29.99",
  "chain": "tron",
  "crypto": "USDT",
  "pay_address": "TU9UkVikcSTHWLFkxmPLqwzWY3LE4Ji13U",
  "pay_amount": "29.87",
  "pay_url": "https://pay.example.com/pay/INV2606028X7K2P9Q",
  "started_at": "2026-06-02T12:00:00Z",
  "expires_at": "2026-06-02T12:10:00Z",
  "hash": "0xabc123...",
  "block": 12345678
}
Response Fields
FieldDescription
sys_noGateway system invoice number
out_noMerchant order number
statusInvoice status: waiting / completed / expired / cancelled
currencyPricing fiat currency
amountPricing amount
chainActual payment chain; null before coin selection
cryptoActual payment crypto; null before coin selection
pay_addressPayment address; null before coin selection
pay_amountOn-chain amount to pay (incl. adjusted tail); null before coin selection
pay_urlPayment page URL
started_atInvoice creation time (ISO8601)
expires_atInvoice expiry time (ISO8601); pay_url is invalid after this
hashOn-chain transaction hash; returned after payment completes
blockBlock height; returned after payment completes
Sync Redirect Parameters (return_url)

On completion, the gateway redirects to your return_url with the following query parameters. Always rely on the async Webhook for fulfillment; the sync redirect is for frontend display only.

ParameterDescription
sys_noGateway system invoice number
out_noMerchant order number
statusAlways completed
signatureSignature; verify with hash_hmac("sha256", sys_no + out_no + status, HMAC_Key), hex
6. Get Deposit Address
GEThttps://pay.example.com/v1/deposit/address?uid={uid}&chain={chain}&crypto={crypto}
ParameterRequiredDescription
uidYesEnd-customer identifier, 1 ~ 128 chars, letters, digits, underscore and hyphen only
chainYesChain code, e.g. tron, base, ethereum
cryptoYesCrypto symbol, e.g. USDT
Response Example
{
  "deposit_address": "0xAbCd1234..."
}
Signing Example (GET)
<?php
// GET 请求没有 body,签名时用空字符串拼接
$timestamp = (string)time();
$nonce     = bin2hex(random_bytes(16));
$signature = hash_hmac('sha256', $nonce . $timestamp, $hmacKey);

$url = $apiBase . '/v1/deposit/address?' . http_build_query([
    'uid'    => 'user-10001',
    'chain'  => 'base',
    'crypto' => 'USDC',
]);
  • The same project, uid and chain always return the same address; safe to call repeatedly.
  • Funds deposited to this address are credited after meeting confirmation requirements and are auto-swept per project configuration.
7. Webhook Callbacks
Delivery URLs
  • Invoices: the notify_url passed when creating the order takes precedence; the project default is used when it is empty.
  • Deposits: the project default notification URL is used.
  • Configure an HTTPS public URL; for security the gateway rejects http, localhost and internal addresses.
Verification & Receipt (must be implemented this way)
<?php
$raw       = file_get_contents('php://input') ?: '';
$nonce     = $_SERVER['HTTP_XC_NONCE']     ?? '';
$timestamp = $_SERVER['HTTP_XC_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_XC_SIGNATURE'] ?? '';

$expected = hash_hmac('sha256', $nonce . $timestamp . $raw, $hmacKey);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

// 幂等:同一个 XC-Nonce 只处理一次(建议用 Redis / 唯一索引去重)
if (!nonceSeenBefore($nonce)) {
    $payload = json_decode($raw, true);
    if (($payload['type'] ?? '') === 'invoice') {
        $data = $payload['data'] ?? [];
        // 幂等入账:以 out_no 为准,金额以 pay_amount 为准
        creditOrder($data['out_no'], $data['pay_amount']);
    }
}

// 必须精确返回 200 + 响应体 ok,否则网关判定投递失败
echo 'ok';
Receipt convention: delivery succeeds only when HTTP 200 is returned and the body equals exactly ok after trimming whitespace. Only network errors and 5xx are retried with exponential backoff; non-200 2xx, 3xx and 4xx are never retried. Per-request timeout is 5 seconds. Always process the same sys_no idempotently.
Retry Strategy & Idempotency
  • Retry interval: exponential backoff, approx. 15s → 30s → 1min → 2min → 4min → 8min …
  • Max retries: 10; after that no more delivery — poll the query endpoint to fetch the status.
  • Idempotency: the same sys_no may be delivered multiple times due to retries — dedup by sys_no before crediting, to avoid duplicate fulfillment.
Invoice Event
{
  "type": "invoice",
  "data": {
    "sys_no": "INV2606028X7K2P9Q",
    "out_no": "order-20260602-001",
    "crypto": "USDT",
    "chain": "tron",
    "pay_address": "TU9UkVikcSTHWLFkxmPLqwzWY3LE4Ji13U",
    "pay_amount": "29.87",
    "hash": "0xabc123...",
    "block": 12345678,
    "confirmed": true,
    "risk_level": null,
    "risk_score": null
  }
}
Deposit Event
{
  "type": "deposit",
  "data": {
    "sys_no": "DXC2606026K9P2QWX",
    "uid": "user-10001",
    "chain": "base",
    "crypto": "USDC",
    "amount": "500",
    "hash": "0xabc123...",
    "block": 12345678,
    "confirmed": true,
    "risk_level": null,
    "risk_score": null
  }
}

risk_level and risk_score are a risk snapshot at notification time; they may temporarily be null while risk control runs asynchronously — do not treat the first notification as the final risk verdict.

8. EPay V1 Compatibility
GET POST https://pay.example.com/epay/submit.php
  • Compatible with common EPay plugins and panels (Xboard, V2board, card-selling systems, WHMCS, etc.) without changing existing integration logic.
  • EPay parameters and signing follow the EPay V1 standard: pid, out_trade_no, money, sign (MD5), sign_type=MD5.
Async Notification Query Fields
FieldDescription
pidEPay merchant ID
trade_noGateway system order number
out_trade_noYour order number
typeEPay compatibility field
nameProduct name
moneyOrder amount (2 decimals)
trade_statusFixed TRADE_SUCCESS
paramExtension parameter passed when ordering; returned only if set
sign_type / signFixed MD5 / EPay MD5 signature
EPay async notifications require an HTTP 200 response with body success (note: different from the native protocol's ok).
9. Error Codes
General Errors
CodeDescriptionHTTP
1000Invalid parameter400
1001Invalid AppID400
1002IP forbidden403
1003Signature error403
1004Project not configured400
1007Duplicate out_no400
1008Timestamp missing or expired400
1009Duplicate request400
Chains & Cryptos
CodeDescriptionHTTP
2000Invalid chain400
2001Invalid crypto400
2002This crypto is not supported on this chain400
Deposit Payments
CodeDescriptionHTTP
4000Invalid UID400
4001No sweep address configured for this chain400
4002Paid invoice count reached the current plan limit403
Invoice Payments
CodeDescriptionHTTP
5000Unsupported fiat currency400
5008No available invoice payment method400
5009Too many pending invoices400
10. Rate Limiting
  • Public query endpoint: 60/minute, per sys_no + IP.
  • Deposit address endpoint: 60/minute, per appid + IP.
  • Rate limiting returns HTTP 429; back off and retry, reusing the same request parameters other than out_no.

When hitting 1003 signature error, check first: whether the signed string is nonce + timestamp + raw body, whether the body matches the sent bytes exactly (do not decode then re-encode), and whether the HMAC result is hex-encoded.