₮ USDT 支付商户门户
← 返回首页 商户登录 立即注册
API 文档

网关地址提供 RESTful 接口 + HMAC-SHA256 签名认证;账单收款、充值收款、Webhook 通知三件事即可覆盖全部收款流程。

1. 概览
网关地址
https://pay.example.com (示例域名;真实地址见接入凭据)
AppID
(审核通过后分配)
HMAC Key
•••••••••••••••• (仅用于服务端签名,请妥善保管) 查看 / 重置
所有 /v1/* 接口除标注公开外,均需携带签名请求头;签名密钥只放在你的服务端,不要下发到浏览器或客户端。
2. 签名机制

1构造请求体(GET 请求没有 body,用空字符串)。

2组装待签字符串:nonce + timestamp + 原始请求体。

3用 HMAC Key 做 HMAC-SHA256,取 hex 结果。

4把四个请求头一并发出。

请求头说明
XC-Appid项目 AppID
XC-Timestamp秒级 Unix 时间戳,过期或缺失会被拒绝
XC-Nonce每次请求唯一的随机串,服务端按它幂等去重
XC-SignatureHMAC-SHA256 签名(hex)
Content-Typeapplication/json
POST 请求示例
<?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,请求体 {"out_no":"o1","amount":"10"},则待签字符串为 a1b2c31717300000{"out_no":"o1","amount":"10"}(直接拼接,无分隔符)。用 HMAC Key 做 HMAC-SHA256 后取 hex 即为 XC-Signature。GET 请求请求体为空字符串,待签字符串为 nonce + timestamp。
3. 接口一览
方法路径说明签名
POST /v1/invoice 创建账单收款,返回支付跳转地址 需要
GET /v1/invoice/{sys_no} 查询账单收款公开状态 公开
GET /v1/deposit/address 获取终端客户的专属充值地址 需要
3.5 链与币种支持

创建账单或获取充值地址时需指定 chain(公链)和 crypto(代币)参数。下表列出系统支持的全部公链与常用代币的 API 参数值。

公链(chain)
名称API 参数类型Gas 代币Chain ID
EthereumethereumEVMETH1
BNB Smart ChainbscEVMBNB56
Polygon PoSpolygonEVMPOL137
Arbitrum Onearbitrum-oneEVMETH42161
OptimismoptimismEVMETH10
BasebaseEVMETH8453
TrontronTronTRX-
代币(crypto)
名称API 参数类型说明
Tether USDUSDTERC-20 / TRC-20稳定币,最常用收款币种
USD CoinUSDCERC-20稳定币,多条 EVM 链可用
DaiDAIERC-20稳定币
EtherETH原生币Ethereum 及 Arbitrum / Optimism / Base 的原生 Gas 币
BNBBNB原生币BNB Smart Chain 的原生 Gas 币
PolygonPOL原生币Polygon PoS 的原生 Gas 币
TRONTRX原生币Tron 的原生 Gas 币
EVM 链支持任意 ERC-20 代币,可在后台添加代币合约地址并启用。Tron 当前仅放行 USDT 与原生 TRX。实际可用的链币组合取决于后台启用的链与币种配置。
4. 创建账单收款
POSThttps://pay.example.com/v1/invoice
字段必填说明
out_no是商户订单号,最长 32 位,同一项目内唯一
title是账单标题,最长 32 位
currency是计价法币代码,支持 USD、CNY 等主流法币
amount是计价金额,字符串,范围 0.00000001 ~ 1000000,最多 8 位小数
duration否有效期分钟数,5 ~ 30,默认 10
methods否限定收款方式,格式 {"币种": ["链码"]}
notify_url否账单级回调地址,优先于项目默认通知地址
return_url否支付完成后的同步跳转地址
请求示例
{
  "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 只决定 amount 的计价单位,买家实际支付的链与币由 methods 决定。
  • 不传 methods 时,系统按项目当前可收款能力生成链币组合;传入时必须是其子集,否则报「无可用账单收款方式」。
  • 买家应支付的链、币、地址、数量一律以账单页或查询接口返回的 chain / crypto / pay_address / pay_amount 为准,不要自己按 amount 推导。
  • 链上金额可能带微调尾数(用于同地址区分不同账单),按 pay_amount 精确支付才能自动匹配。
  • 拿到 pay_url 后引导用户打开即可完成选币与付款。
  • pay_url 有效期等于账单 duration(默认 10 分钟),过期后链接失效需重新创建账单。
5. 查询账单收款
GEThttps://pay.example.com/v1/invoice/{sys_no}
  • 公开接口,无需签名,适合前端轮询展示支付结果。
  • 建议轮询间隔 5 ~ 15 秒;status 为 completed 即视为支付完成(无需再判断 confirmed)。
  • expires_at 到期后账单会变为 expired 状态,请在此之前完成付款。
  • 若下单时传入了 return_url,账单完成时该字段会返回带签名的同步跳转地址;发货逻辑仍应以 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
}
响应字段
字段说明
sys_no网关系统账单号
out_no商户订单号
status账单状态:waiting(待支付)/ completed(已完成)/ expired(已过期)/ cancelled(已取消)
currency计价法币
amount计价金额
chain实际收款链,未选币时为 null
crypto实际收款币种,未选币时为 null
pay_address收款地址,未选币时为 null
pay_amount应付链上金额(含微调尾数),未选币时为 null
pay_url支付页地址
started_at账单创建时间(ISO8601)
expires_at账单过期时间(ISO8601),过期后 pay_url 失效
hash链上交易哈希,支付完成后返回
block区块高度,支付完成后返回
同步跳转参数(return_url)

账单完成时,网关会跳转到你传入的 return_url,并在 query 中附带以下参数。发货逻辑请以 Webhook 异步通知为准,同步跳转仅用于前端展示。

参数说明
sys_no网关系统账单号
out_no商户订单号
status固定为 completed
signature签名,验签方式:hash_hmac("sha256", sys_no + out_no + status, HMAC_Key),取 hex
6. 获取充值收款地址
GEThttps://pay.example.com/v1/deposit/address?uid={uid}&chain={chain}&crypto={crypto}
参数必填说明
uid是终端客户标识,1 ~ 128 位,仅字母、数字、下划线、中划线
chain是链代码,如 tron、base、ethereum
crypto是币种符号,如 USDT
响应示例
{
  "deposit_address": "0xAbCd1234..."
}
签名示例(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',
]);
  • 同一项目、同一 uid、同一链会稳定返回同一个地址,可放心重复调用。
  • 充值到该地址的资金在达到确认要求后入账,并按项目配置自动归集。
7. Webhook 回调
投递地址
  • 账单收款:优先使用下单时传入的 notify_url,为空时使用项目默认通知地址。
  • 充值收款:使用项目默认通知地址。
  • 请配置 HTTPS 公网地址;网关出于安全考虑会拒绝 http、localhost 与内网地址。
验签与回执(必须这样写)
<?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';
回执约定:HTTP 200 且响应体去除首尾空白后恰好等于 ok 才算投递成功。只有网络错误与 5xx 会按指数退避重试,2xx 非 200、3xx、4xx 一律不重试;单次请求超时 5 秒。请务必保证同一 sys_no 幂等处理。
重试策略与幂等
  • 重试间隔:指数退避,约 15s → 30s → 1min → 2min → 4min → 8min …
  • 最大重试次数:10 次;超过后不再投递,请通过查询接口主动拉取状态。
  • 幂等:同一 sys_no 可能因重试被投递多次,请按 sys_no 去重入账,避免重复发货。
账单收款事件
{
  "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 与 risk_score 是发通知时的风险快照;风控异步执行时可能暂时为 null,不要把首条通知当作最终风控结论。

8. 易支付 V1 兼容
GET POST https://pay.example.com/epay/submit.php
  • 适配常见易支付插件与面板(Xboard、V2board、发卡系统、WHMCS 等),无需改造原有对接逻辑。
  • EPay 参数与签名规则见易支付 V1 标准:pid、out_trade_no、money、sign(MD5)、sign_type=MD5。
异步通知 query 字段
字段说明
pidEPay 商户 ID
trade_no网关系统订单号
out_trade_no你的订单号
typeEPay 兼容字段
name商品名称
money订单金额(两位小数)
trade_status固定 TRADE_SUCCESS
param下单时传入的扩展参数,有值才返回
sign_type / sign固定 MD5 / EPay MD5 签名
EPay 异步通知要求响应 HTTP 200 且响应体为 success(注意与原生协议的 ok 不同)。
9. 错误码
通用错误
错误码说明HTTP
1000参数错误400
1001AppID 无效400
1002IP 禁止403
1003签名错误403
1004项目未配置400
1007单号 out_no 重复400
1008Timestamp 未设置或过期400
1009请求重复400
链与币种
错误码说明HTTP
2000无效链400
2001无效加密货币400
2002本链不支持此加密货币400
充值收款
错误码说明HTTP
4000无效 UID400
4001项目未配置该链的归集收款地址400
4002成功支付账单数已达当前套餐上限403
账单收款
错误码说明HTTP
5000不支持的计价法币400
5008无可用账单收款方式400
5009待支付记录过多400
10. 限流
  • 公开查询接口:60/minute,按 sys_no + IP 维度。
  • 充值地址接口:60/minute,按 appid + IP 维度。
  • 触发限流返回 HTTP 429,请退避重试并复用同一 out_no 之外的请求参数。

遇到 1003 签名错误 时,优先检查:待签字符串是否为 nonce + timestamp + 原始body、body 是否与发送的字节完全一致(不要先 decode 再 encode)、HMAC 结果是否取了 hex。