回调处理
回调处理
回调是订单状态的最终依据。至少投递一次、以 HTTP POST 发送，你必须在 5 秒内应答 —— 超时视为失败并触发重试。
最后更新 2026-10-24
代收回调参数
status 2 表示成功，3 表示失败。utr 只在成功时出现，某些通道可能为空。
| 字段 | 类型 | 说明 |
|---|---|---|
| platform_order_no | string | 平台订单号 |
| merchant_order_no | string | 你的订单号 |
| amount | string | 订单金额字符串，如 "1000.00" |
| actual_amount | string | 实际支付金额 |
| fee | string | 手续费，如 "30.00" |
| status | int | 2 成功，3 失败 |
| utr | string | 银行流水号，仅成功时 |
| sign | string | MD5 签名 |
先验签再处理
必须使用收到的原始值 —— 不要重新格式化 amount 或 fee。把 "1000" 格式化成 "1000.00" 会改变哈希，导致全部回调验签失败。
$data = json_decode(file_get_contents('php://input'), true);
$calc = md5(
$data['platform_order_no'] .
$data['merchant_order_no'] .
$data['amount'] .
$data['fee'] .
$data['status'] .
$key
);
if (!hash_equals($calc, $data['sign'] ?? '')) {
http_response_code(403);
exit('SIGN ERROR');
}
// idempotency: platform_order_no is the key
if (alreadyProcessed($data['platform_order_no'])) {
echo 'SUCCESS';
exit;
}
if ((int)$data['status'] === 2) {
markOrderPaid($data['merchant_order_no'], $data['actual_amount'], $data['utr'] ?? '');
}
echo 'SUCCESS';能避免大多数对接事故的几条规则
5 秒内应答。重活异步做 —— 落库、返回 SUCCESS，再处理业务。
保证幂等。同一订单可能收到多次回调；以 platform_order_no 作为写入的幂等键。
没有验签就不要信回调体。一条伪造回调穿过你的处理器，就是一单白送。
不要依赖回调顺序。代付的迟到重投可能让冲正出现在成功之后 —— 一律以最新状态查询为准对账。
常见问题
我的接口挂了会怎样？
会重试投递。用 collectStatus 或 payoutStatus 对账可以立刻补齐，不用等重试。
用的是 HMAC 吗？
不是 —— 是拼接值加密钥后取 MD5。回调地址用 HTTPS 并严格验签，就是这套安全模型。