1构造请求体(GET 请求没有 body,用空字符串)。
2组装待签字符串:nonce + timestamp + 原始请求体。
3用 HMAC Key 做 HMAC-SHA256,取 hex 结果。
4把四个请求头一并发出。
| 请求头 | 说明 |
|---|---|
| XC-Appid | 项目 AppID |
| XC-Timestamp | 秒级 Unix 时间戳,过期或缺失会被拒绝 |
| XC-Nonce | 每次请求唯一的随机串,服务端按它幂等去重 |
| XC-Signature | HMAC-SHA256 签名(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,请求体 {"out_no":"o1","amount":"10"},则待签字符串为 a1b2c31717300000{"out_no":"o1","amount":"10"}(直接拼接,无分隔符)。用 HMAC Key 做 HMAC-SHA256 后取 hex 即为 XC-Signature。GET 请求请求体为空字符串,待签字符串为 nonce + timestamp。 | 方法 | 路径 | 说明 | 签名 |
|---|---|---|---|
| POST | /v1/invoice | 创建账单收款,返回支付跳转地址 | 需要 |
| GET | /v1/invoice/{sys_no} | 查询账单收款公开状态 | 公开 |
| GET | /v1/deposit/address | 获取终端客户的专属充值地址 | 需要 |
创建账单或获取充值地址时需指定 chain(公链)和 crypto(代币)参数。下表列出系统支持的全部公链与常用代币的 API 参数值。
| 名称 | API 参数 | 类型 | Gas 代币 | 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 | - |
| 名称 | API 参数 | 类型 | 说明 |
|---|---|---|---|
| Tether USD | USDT | ERC-20 / TRC-20 | 稳定币,最常用收款币种 |
| USD Coin | USDC | ERC-20 | 稳定币,多条 EVM 链可用 |
| Dai | DAI | ERC-20 | 稳定币 |
| Ether | ETH | 原生币 | Ethereum 及 Arbitrum / Optimism / Base 的原生 Gas 币 |
| BNB | BNB | 原生币 | BNB Smart Chain 的原生 Gas 币 |
| Polygon | POL | 原生币 | Polygon PoS 的原生 Gas 币 |
| TRON | TRX | 原生币 | Tron 的原生 Gas 币 |
| 字段 | 必填 | 说明 |
|---|---|---|
| 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 分钟),过期后链接失效需重新创建账单。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,并在 query 中附带以下参数。发货逻辑请以 Webhook 异步通知为准,同步跳转仅用于前端展示。
| 参数 | 说明 |
|---|---|
| sys_no | 网关系统账单号 |
| out_no | 商户订单号 |
| status | 固定为 completed |
| signature | 签名,验签方式:hash_hmac("sha256", sys_no + out_no + status, HMAC_Key),取 hex |
| 参数 | 必填 | 说明 |
|---|---|---|
| uid | 是 | 终端客户标识,1 ~ 128 位,仅字母、数字、下划线、中划线 |
| chain | 是 | 链代码,如 tron、base、ethereum |
| crypto | 是 | 币种符号,如 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、同一链会稳定返回同一个地址,可放心重复调用。notify_url,为空时使用项目默认通知地址。<?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 且响应体去除首尾空白后恰好等于 ok 才算投递成功。只有网络错误与 5xx 会按指数退避重试,2xx 非 200、3xx、4xx 一律不重试;单次请求超时 5 秒。请务必保证同一 sys_no 幂等处理。 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,不要把首条通知当作最终风控结论。
pid、out_trade_no、money、sign(MD5)、sign_type=MD5。| 字段 | 说明 |
|---|---|
| pid | EPay 商户 ID |
| trade_no | 网关系统订单号 |
| out_trade_no | 你的订单号 |
| type | EPay 兼容字段 |
| name | 商品名称 |
| money | 订单金额(两位小数) |
| trade_status | 固定 TRADE_SUCCESS |
| param | 下单时传入的扩展参数,有值才返回 |
| sign_type / sign | 固定 MD5 / EPay MD5 签名 |
200 且响应体为 success(注意与原生协议的 ok 不同)。 | 错误码 | 说明 | HTTP |
|---|---|---|
| 1000 | 参数错误 | 400 |
| 1001 | AppID 无效 | 400 |
| 1002 | IP 禁止 | 403 |
| 1003 | 签名错误 | 403 |
| 1004 | 项目未配置 | 400 |
| 1007 | 单号 out_no 重复 | 400 |
| 1008 | Timestamp 未设置或过期 | 400 |
| 1009 | 请求重复 | 400 |
| 错误码 | 说明 | HTTP |
|---|---|---|
| 2000 | 无效链 | 400 |
| 2001 | 无效加密货币 | 400 |
| 2002 | 本链不支持此加密货币 | 400 |
| 错误码 | 说明 | HTTP |
|---|---|---|
| 4000 | 无效 UID | 400 |
| 4001 | 项目未配置该链的归集收款地址 | 400 |
| 4002 | 成功支付账单数已达当前套餐上限 | 403 |
| 错误码 | 说明 | HTTP |
|---|---|---|
| 5000 | 不支持的计价法币 | 400 |
| 5008 | 无可用账单收款方式 | 400 |
| 5009 | 待支付记录过多 | 400 |
60/minute,按 sys_no + IP 维度。60/minute,按 appid + IP 维度。429,请退避重试并复用同一 out_no 之外的请求参数。遇到 1003 签名错误 时,优先检查:待签字符串是否为 nonce + timestamp + 原始body、body 是否与发送的字节完全一致(不要先 decode 再 encode)、HMAC 结果是否取了 hex。