回调通知

当订单状态变更（支付成功 / 超时）时，系统会向你在创建订单时提供的 notify_url 推送 POST 请求。

通知参数

参数名	类型	说明
trade_id	string	系统交易 ID
order_id	string	商户订单编号
amount	number	请求支付金额（法币）
actual_amount	number	实际支付金额（加密货币）
token	string	收款地址
block_transaction_id	string	区块链交易哈希
signature	string	签名字符串
status	number	1 待支付 / 2 支付成功 / 3 支付超时

通知示例

POST https://your.site/notify
Content-Type: application/json

{
  "trade_id": "b3d2477c-d945-41da-96b7-f925bbd1b415",
  "order_id": "20250120001",
  "amount": 28.88,
  "actual_amount": 4.25,
  "token": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "block_transaction_id": "12ef6267b42e43959795cf31808d0cc72b3d0a48953ed19c61d4b6665a341d10",
  "signature": "1cd4b52df5587cfb1968b0c0c6e156cd",
  "status": 2
}

验签

使用与请求相同的签名算法验证 signature：

1. 除去 signature，其它参数按字典序排序
2. 拼接成 key=value&key=value
3. 末尾追加 API Token
4. MD5 后转小写
5. 与收到的 signature 比对

响应要求

场景	返回
成功接收	字符串 success（不区分大小写）
失败 / 未处理	其他内容，系统会按退避策略重试

必须返回 success，否则系统会重复推送。

处理示例（PHP）

<?php
$token = 'your_api_token_here';

$raw = file_get_contents('php://input');
$data = json_decode($raw, true);

if (!$data) {
    http_response_code(400);
    echo 'invalid json';
    exit;
}

$receivedSign = $data['signature'] ?? '';
unset($data['signature']);

ksort($data);
$pairs = [];
foreach ($data as $k => $v) {
    if ($v === null || $v === '') continue;
    $pairs[] = $k . '=' . $v;
}
$signStr = implode('&', $pairs) . $token;
$expectedSign = strtolower(md5($signStr));

if ($expectedSign !== $receivedSign) {
    http_response_code(403);
    echo 'invalid signature';
    exit;
}

$orderId = $data['order_id'];
$status = (int)$data['status'];

if ($status === 2) {
    // 支付成功，更新你自己的订单（注意幂等）
} elseif ($status === 3) {
    // 支付超时
}

echo 'success';

注意事项

1. 幂等处理：同一笔订单可能收到多次通知，业务逻辑必须幂等
2. 异步处理：业务耗时长时，先返回 success 再异步处理
3. 重试机制：返回非 success 时，系统会按退避策略重试推送
4. 来源验证：务必验证签名，防止伪造通知