USDT · ERC20商户 API

USDT 收款通道 · API 用法

别的平台 / 你的系统通过 channel=usdt_erc20 走本通道： 下单 → 付款人往你登记的 ERC20 地址转账 → 平台链上监听判到账 → 回调通知你。钱直接进你的钱包，平台只读监听。

① 三步开始

1注册并登录，在用户中心 · API 凭证签发 app_id + secret（secret 只显示一次）。

2在本页「通道配置」登记你的 ERC20 收款地址并邮箱验证通过（地址必须是 0x 开头、42 位十六进制）。

3对每个请求做 HMAC 签名（见 ②），调端点（见 ③）。

② 鉴权：HMAC-SHA256 签名

每个请求带 4 个头：

请求头	内容
X-Pay-App-Id	你的 app_id
X-Pay-Timestamp	秒级 Unix 时间戳（±300 秒窗口）
X-Pay-Nonce	64 位十六进制随机串（防重放，服务端去重）
X-Pay-Signature	strtolower(hex(HMAC_SHA256(secret, 规范串)))

规范串（每行一个 \n，末尾不加）：

pay-req-v1
{timestamp}
{nonce}
{METHOD} {path}          ← 例：POST /pay/v1/orders.php（path 不含查询串）
{sha256_hex(raw_body)}   ← 无 body 用空串的 sha256

③ 本通道端点

方法	路径	说明
POST	/pay/v1/orders.php	创建订单（channel=usdt_erc20）
GET	/pay/v1/orders.php?out_trade_no=…	按平台单号查单
GET	/pay/v1/orders.php?merchant_no=…	按你自己的单号查单
POST	/pay/v1/orders_close.php	关闭未支付订单
GET	/pay/v1/payout_methods.php	我的收款方式（含状态 / 收款上限档位）
GET	/pay/v1/statements.php	订单流水（对账）

④ 创建订单（POST /pay/v1/orders.php）

JSON body（ERC20 通道）：

字段	必填	说明
base_amount	★	收款金额（字符串，最多 6 位小数）—— 由你（商户）定
channel		本通道固定 usdt_erc20（不填默认也是它）
merchant_no		你自己的单号（回显 + 可按它查单）
subject		商品名（≤128 字符）
notify_url		到账回调地址（HMAC 签名推送）
expires_in		有效期秒数（60~7200，默认 1800）

响应含 out_trade_no（平台单号）、pay_amount（精确应付金额）、 pay_address（收款 ERC20 地址）。把这两样展示给付款人： 向这个地址转这个金额。付款上限受你登记的收款上限档位约束（超过档位的单会被拒绝）。

ERC20 到账判定：付款金额 = 订单金额 + 两位小数尾数（如 12.50 → 12.53，尾数随机 0.01~0.99、唯一对应一单）、不依赖备注；链上入账 12 个确认判为已到账，之后记账并发回调。 幂等：带 Idempotency-Key 头时同一商户 24 小时内同 key 只会有一单，重试拿原单。

⑤ PHP 示例（签名 + 下单）

function sign(array $headers, string $method, string $path, string $body, string $secret): string {
    $canon = "pay-req-v1\n{$headers['X-Pay-Timestamp']}\n{$headers['X-Pay-Nonce']}\n"
           . strtoupper($method) . ' ' . $path . "\n"
           . hash('sha256', $body);
    return strtolower(hash_hmac('sha256', $canon, $secret));
}

$appId  = '你的 app_id';
$secret = '你的 secret';
$nonce  = bin2hex(random_bytes(32));
$ts     = (string)time();
$body   = json_encode([
    'base_amount' => '12.50',          // 收款金额（你定）
    'channel'     => 'usdt_erc20',     // ERC20 通道
    'merchant_no' => 'ORD-20260930-1',
    'subject'     => '会员充值',
    'notify_url'  => 'https://your.site/pay/notify.php',
], JSON_UNESCAPED_UNICODE);

$path = '/pay/v1/orders.php';
$sig  = sign([
    'X-Pay-Timestamp' => $ts,
    'X-Pay-Nonce'     => $nonce,
], 'POST', $path, $body, $secret);

$ch = curl_init('https://api.wanminguo.top' . $path);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $body,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Pay-App-Id: '     . $appId,
        'X-Pay-Timestamp: '  . $ts,
        'X-Pay-Nonce: '      . $nonce,
        'X-Pay-Signature: '  . $sig,
        'Idempotency-Key: '  . 'ORD-20260930-1',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$resp = curl_exec($ch);      // {"ok":true,"order":{"out_trade_no":"…","pay_amount":"12.53","pay_address":"0x…"}}
echo $resp;

⑥ 到账回调（notify_url）

判到账后平台 POST 到你下单时的 notify_url，同样带 4 个 X-Pay-* 头，规范串是回调版（无「方法+路径」行）：

pay-cb-v1
{timestamp}
{nonce}
{sha256_hex(raw_body)}

body 含 out_trade_no / merchant_no / paid_amount / status=paid。验签 + 按 out_trade_no 幂等处理，响应 {"ok":true}；失败进入重试队列（每分钟重试，最长 24 小时）。重复回调不会重复入账。

⑦ 安全须知

secret 只在签发时显示一次；丢了去用户中心重新签发（旧的立即作废）。
平台绝对不要你的私钥/助记词 —— 收款地址是你自己的，平台只读监听链上公开转账。
回调务必验签再更新订单，并核对金额与单号，防止伪造回调。
ERC20 地址复制务必逐位核对（0x 开头、42 位十六进制），错一位就会丢币。

端点清单（JSON）见 /pay/v1/；凭证管理在用户中心 · API 凭证。