对接文档

回调

代付有结果、代收付款成功时，我们把结果 POST 到您给的回调地址。收到后先落库，再回 success。

回调只发往公网地址：回调地址写的是内网、本机这类 IP（127.0.0.1、10.x、192.168.x 等）的，提交时就拒；域名解析到这类地址的，到发的时候不发，按一次失败算、照常重试。

代付回调 std1

状态变成 SUCCESS、FAILED 时各发一次；冲正（REVERSED）不发回调，您靠查单看到。提代付时没给 notifyUrl 就不发，您靠查单。

项目值
方法POST
Content-Typeapplication/x-www-form-urlencoded; charset=UTF-8
地址您给的地址原样用；地址上自带的查询串留在地址里、不参与签名
超时连接 5 秒，读取 15 秒
跳转不跟随跳转：请直接给最终地址
HTTPS 证书不校验证书（自签证书也能收）
判成功HTTP 200–299，正文去掉首尾空白后不分大小写等于 success（开头一个 BOM 会先去掉）
没收到 success 时重发首发之后隔 1、2、5、10、30、60 分钟各发一次，共 7 次；用完就停
新状态同一笔有了新状态的回调，旧状态还没发完的重发就作废

字段

参数什么时候有说明
mchId总有商户号
mchOrderNo总有商户单号
payoutNo总有本平台代付单号
amount总有代付金额（最小单位）
fee总有手续费（最小单位），受理时定下
currency总有币种
status总有代付状态，见下面「状态」
createTime总有受理时间，北京时间
finishTimestatus 是 FAILED / SUCCESS 时有进入当前状态的时间
failMsgstatus 是 FAILED 时有撤单原因
remark总有申请时的备注
sign总有签名

示例

示例密钥（假的）：0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef；示例商户号：DEMO0001

回调正文

mchId=DEMO0001&mchOrderNo=ORDER-20260917-0001&payoutNo=P20260917120000000001&amount=10000&fee=200&currency=CNY&status=SUCCESS&createTime=2026-09-17+12%3A00%3A00&finishTime=2026-09-17+12%3A05%3A30&remark=%E6%B5%8B%E8%AF%95&sign=f6b9b82e927528961584530bcd383b5dc360d3b453f7ba195fb41c986f519e61

签名串

amount=10000&createTime=2026-09-17 12:00:00&currency=CNY&fee=200&finishTime=2026-09-17 12:05:30&mchId=DEMO0001&mchOrderNo=ORDER-20260917-0001&payoutNo=P20260917120000000001&remark=测试&status=SUCCESS

sign

f6b9b82e927528961584530bcd383b5dc360d3b453f7ba195fb41c986f519e61

您要做的

  1. 只用 POST 正文验签。别用框架合并好的参数表（Java getParameterMap、PHP $_POST／$_REQUEST、Go r.Form、ASP.NET Request.Form、Flask request.values、Express express.urlencoded()），它们会把地址上的查询串混进来。
  2. 验签，再核 mchId 是您自己的，然后按 payoutNo＋status 去重。
  3. 同一笔只接受往后走的状态：PROCESSING < SUCCESS = FAILED < REVERSED。回调可能晚到、重复到，以查单为准。
  4. 先落库，再回 HTTP 200、正文 success。PHP 文件别带 BOM，success 前后别输出别的东西。

代收回调 compat1（老协议）

订单付款成功后发；运营补单成功后、您查单带 executeNotify=true 时也会再发。和原来老系统一样：

项目值
方法POST
Content-Typeapplication/x-www-form-urlencoded
超时连接 5 秒，读取 15 秒
跳转不跟随跳转：请直接给最终地址
HTTPS 证书不校验证书（自签证书也能收）
判成功正文去掉首尾空白后不分大小写等于 success；HTTP 400 及以上算失败
没收到 success 时重发首发之后隔 1、2、3、4、5 分钟各发一次，共 6 次；用完就停
顺序参数顺序固定（就是下表的顺序），不是按字母排

字段

顺序参数说明
1income实收金额（最小单位）；通道重算过金额时和 amount 不同
2payOrderId商户单号
3amount下单金额（最小单位）
4mchId商户号
5productId正式产品ID编码请联系客服提供
6mchOrderNo商户单号
7paySuccTime成功时间，毫秒数；没有时为空
8sign签名（MD5，空值不参与）
9channelOrderNo上游单号
10backType固定 2
11param1下单时的 param1
12param2付款人姓名
13channelAttach上游附加数据
14status订单状态：2 支付成功，3 业务完成

示例

示例密钥（假的）：demo-key-NOT-REAL-do-not-use-0001

您填的 notifyUrl

https://merchant.example.com/notify

发往的地址

https://merchant.example.com/notify

回调正文

income=10000&payOrderId=ORDER20260918001&amount=10000&mchId=20000001&productId=8001&mchOrderNo=ORDER20260918001&paySuccTime=1789704005000&sign=9447B44CF966CB47A625CADF63C539A8&channelOrderNo=UP20260918000123&backType=2&param1=shop-7&param2=%E5%BC%A0%E4%B8%89&channelAttach=&status=2

签名串

amount=10000&backType=2&channelOrderNo=UP20260918000123&income=10000&mchId=20000001&mchOrderNo=ORDER20260918001&param1=shop-7&param2=张三&payOrderId=ORDER20260918001&paySuccTime=1789704005000&productId=8001&status=2&key=demo-key-NOT-REAL-do-not-use-0001

回调地址自带 ? 时，照老系统的拼法：您地址上的查询串挪到正文开头，我们的第一个参数紧跟在它后面（例如 shop=7?income=10000&…）。原来老系统就是这样发的，您原来能收，现在照样能收：

示例密钥（假的）：demo-key-NOT-REAL-do-not-use-0001

您填的 notifyUrl

https://merchant.example.com/notify?shop=7

发往的地址

https://merchant.example.com/notify

回调正文

shop=7?income=10000&payOrderId=ORDER20260918001&amount=10000&mchId=20000001&productId=8001&mchOrderNo=ORDER20260918001&paySuccTime=1789704005000&sign=9447B44CF966CB47A625CADF63C539A8&channelOrderNo=UP20260918000123&backType=2&param1=shop-7&param2=%E5%BC%A0%E4%B8%89&channelAttach=&status=2

您要做的

  1. 用收到的参数验签（MD5，见 签名）。
  2. 按商户单号去重：同一笔可能不止收到一次（补发、查单带 executeNotify=true 触发的补发）。
  3. 先落库，再回 success。

回调来源 IP

我们从这些 IP 发回调：47.242.183.76。您对回调来源设了白名单的，把它们加进去。从老系统迁来的商户，老系统的 IP 先别删：切换前下的单还会从老系统回调。

回调请求头 User-Agent 固定是 WebhookClient/1.0（代付、代收回调都一样）。您的防火墙或 CDN 按 User-Agent 拦截的，请放行它。它只用来识别来源，验真伪以签名为准。