Gateway AddressProvides a RESTful API with HMAC-SHA256 signature authentication; invoice payments, deposit payments and Webhook notifications cover the entire payment flow.
/v1/* endpoints require signed request headers unless marked Public. Keep the signing key on your server only; never ship it to browsers or clients. 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.
| Header | Description |
|---|---|
| XC-Appid | Project AppID |
| XC-Timestamp | Unix timestamp in seconds; expired or missing values are rejected |
| XC-Nonce | Random string unique per request; the server uses it for idempotent dedup |
| XC-Signature | HMAC-SHA256 signature (hex) |
| Content-Type | application/json |
<?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']); // 跳转到支付页
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. | Method | Path | Description | Signature |
|---|---|---|---|
| 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 |
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.
| Name | API Parameter | Type | Gas Token | Chain ID |
|---|---|---|---|---|
| Ethereum | ethereum | EVM | ETH | 1 |
| BNB Smart Chain | bsc | EVM | BNB | 56 |
| Polygon PoS | polygon | EVM | POL | 137 |
| Arbitrum One | arbitrum-one | EVM | ETH | 42161 |
| Optimism | optimism | EVM | ETH | 10 |
| Base | base | EVM | ETH | 8453 |
| Tron | tron | Tron | TRX | - |
| Name | API Parameter | Type | Description |
|---|---|---|---|
| Tether USD | USDT | ERC-20 / TRC-20 | Stablecoin, most common payment crypto |
| USD Coin | USDC | ERC-20 | Stablecoin, available on multiple EVM chains |
| Dai | DAI | ERC-20 | Stablecoin |
| Ether | ETH | Native | Native gas token of Ethereum, Arbitrum, Optimism, Base |
| BNB | BNB | Native | Native gas token of BNB Smart Chain |
| Polygon | POL | Native | Native gas token of Polygon PoS |
| TRON | TRX | Native | Native gas token of Tron |
| Field | Required | Description |
|---|---|---|
| out_no | Yes | Merchant order number, up to 32 chars, unique within the project |
| title | Yes | Invoice title, up to 32 chars |
| currency | Yes | Fiat currency code; supports USD, CNY and other major fiats |
| amount | Yes | Amount as string, range 0.00000001 ~ 1000000, up to 8 decimals |
| duration | No | Validity in minutes, 5 ~ 30, default 10 |
| methods | No | Restrict payment methods, format {"crypto": ["chain"]} |
| notify_url | No | Invoice-level callback URL, takes precedence over the project default |
| return_url | No | Sync redirect URL after payment completion |
{
"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"
}
{
"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"
}
currency only determines the pricing unit of amount; the chain and crypto the buyer actually pays with are decided by methods.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.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.pay_amount is required for automatic matching.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.status is completed (do not rely on confirmed).expired after expires_at; payment must be completed before that.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.{
"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
}
| Field | Description |
|---|---|
| sys_no | Gateway system invoice number |
| out_no | Merchant order number |
| status | Invoice status: waiting / completed / expired / cancelled |
| currency | Pricing fiat currency |
| amount | Pricing amount |
| chain | Actual payment chain; null before coin selection |
| crypto | Actual payment crypto; null before coin selection |
| pay_address | Payment address; null before coin selection |
| pay_amount | On-chain amount to pay (incl. adjusted tail); null before coin selection |
| pay_url | Payment page URL |
| started_at | Invoice creation time (ISO8601) |
| expires_at | Invoice expiry time (ISO8601); pay_url is invalid after this |
| hash | On-chain transaction hash; returned after payment completes |
| block | Block height; returned after payment completes |
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.
| Parameter | Description |
|---|---|
| sys_no | Gateway system invoice number |
| out_no | Merchant order number |
| status | Always completed |
| signature | Signature; verify with hash_hmac("sha256", sys_no + out_no + status, HMAC_Key), hex |
| Parameter | Required | Description |
|---|---|---|
| uid | Yes | End-customer identifier, 1 ~ 128 chars, letters, digits, underscore and hyphen only |
| chain | Yes | Chain code, e.g. tron, base, ethereum |
| crypto | Yes | Crypto symbol, e.g. USDT |
{
"deposit_address": "0xAbCd1234..."
}
<?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',
]);
uid and chain always return the same address; safe to call repeatedly.notify_url passed when creating the order takes precedence; the project default is used when it is empty.<?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';
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. sys_no may be delivered multiple times due to retries — dedup by sys_no before crediting, to avoid duplicate fulfillment.{
"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
}
}
{
"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.
pid, out_trade_no, money, sign (MD5), sign_type=MD5.| Field | Description |
|---|---|
| pid | EPay merchant ID |
| trade_no | Gateway system order number |
| out_trade_no | Your order number |
| type | EPay compatibility field |
| name | Product name |
| money | Order amount (2 decimals) |
| trade_status | Fixed TRADE_SUCCESS |
| param | Extension parameter passed when ordering; returned only if set |
| sign_type / sign | Fixed MD5 / EPay MD5 signature |
200 response with body success (note: different from the native protocol's ok). | Code | Description | HTTP |
|---|---|---|
| 1000 | Invalid parameter | 400 |
| 1001 | Invalid AppID | 400 |
| 1002 | IP forbidden | 403 |
| 1003 | Signature error | 403 |
| 1004 | Project not configured | 400 |
| 1007 | Duplicate out_no | 400 |
| 1008 | Timestamp missing or expired | 400 |
| 1009 | Duplicate request | 400 |
| Code | Description | HTTP |
|---|---|---|
| 2000 | Invalid chain | 400 |
| 2001 | Invalid crypto | 400 |
| 2002 | This crypto is not supported on this chain | 400 |
| Code | Description | HTTP |
|---|---|---|
| 4000 | Invalid UID | 400 |
| 4001 | No sweep address configured for this chain | 400 |
| 4002 | Paid invoice count reached the current plan limit | 403 |
| Code | Description | HTTP |
|---|---|---|
| 5000 | Unsupported fiat currency | 400 |
| 5008 | No available invoice payment method | 400 |
| 5009 | Too many pending invoices | 400 |
60/minute, per sys_no + IP.60/minute, per appid + IP.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.