代付 API 对接文档

本文档面向商户接入代付（出款）业务。商户通过签名请求向平台发起代付，平台异步回调代付结果，商户验签后入账。

1. 基本信息

2. 代付下单

2.1 请求参数

2.2 响应

成功：

{"status":"success","msg":"代付申请成功","transaction_id":"P0622295680986222eb"}

失败：

{"status":"error","msg":"错误原因","data":[]}

transaction_id 为平台系统订单号，请保存以便对账。

3. 代付结果回调

代付完成后，平台向商户 notifyurl 发送 POST（x-www-form-urlencoded）。

3.1 回调参数

4. 签名算法

4.1 下单签名（商户生成）

1. 取所有非空业务参数（不含 pay_md5sign），按参数名 ASCII 升序排序（ksort）。
2. 拼接为 k1=v1&k2=v2&...&（每项后带 &）。
3. 末尾追加 key=APIKEY。
4. pay_md5sign = strtoupper(md5(上述字符串))。

// 待签名串（已按 ksort 排序，末尾接 key）
accountname=收款人&bankname=银行&cardnumber=卡号&city=Hanoi&mchid=10464&money=5000000.00¬ifyurl=https://.../notify&out_trade_no=ORDER123&province=Hanoi&r_time=1782129600&subbranch=支行&key=APIKEY
// MD5 后转大写即为 pay_md5sign

4.2 回调验签（商户校验）

回调签名参数按固定顺序拼接（不排序）：mchid → orderid → sysorderid → money → status → remark → timestamp，跳过空值，末尾追加 key=APIKEY，MD5 转大写后与 pay_md5sign 比对。

$str = "mchid={mchid}&orderid={orderid}&sysorderid={sysorderid}&money={money}&status={status}&remark={remark}×tamp={timestamp}&key=APIKEY";
$sign = strtoupper(md5($str));   // 与回调中的 pay_md5sign 比对，一致即验签通过

回调: mchid=10464 orderid=FORMALPAYOUT20260622195927 sysorderid=P0622295680986222eb
      money=5000000.000 status=1 remark=1 timestamp=1782129602
      pay_md5sign=AF57C47007307A93229FC48DAF2EA2F2
商户重算 → AF57C47007307A93229FC48DAF2EA2F2  ✓ 一致

5. 接入自测步骤

1. 用测试 mchid/apikey 按 4.1 生成签名，POST 下单接口，确认返回 success + transaction_id。
2. 提供可访问的 notifyurl（公网 HTTPS），实现：验签 → 入账 → 返回 success。
3. 等待平台回调，确认收到参数、验签通过、并正确返回 success（平台不再重试即为成功）。
4. 核对 status：1 成功入账，2 失败需退款/标记。

6. 常见错误

如需测试商户号/密钥或加白 IP，请联系平台对接人。