代付回调

平台向该订单的 notify_url 发送 POST JSON。不传 notify_url 则没有该订单回调；浏览器 return_url 与回调无关。

回调字段

字段	类型	要求	说明
tenant_id	string	必填	商户编号。
platform_order_no	string	必填	平台订单号。
tenant_order_no	string	必填	商户订单号。
status	integer	必填	结果状态；成功为 20。
pay_time	string	选填	付款确认时间；失败等情况下为空值会省略。
amount	string	必填	原订单金额，不是手续费扣除后的金额，也不是实付金额字段。
total_fee	string	必填	该订单手续费。
settlement_amount	string	必填	代收通常是金额减手续费；代付通常是金额加手续费。
created_at	string	必填	订单创建时间。
utr	string	选填	取得时返回支付参考号；没有时省略。
notify_remark	string	选填	建单备注，非空时返回。
signature	string	必填	回调签名字段；计算时排除它，不是排除 sign。
refund_at	string	选填	冲正时可返回的退款时间；如出现，参与验签。
refund_reason	string	选填	冲正时可返回的说明；不是统一的详细失败原因字段。

日期采用 YYYY-MM-DD HH:mm:ss，不是 ISO8601。验签时保留原值。选填字段为空可省略。代收、代付的金额含义不同。

成功回调正文

{
  "tenant_id": "DEMO0001",
  "platform_order_no": "PRT202610051700DEMO0001",
  "tenant_order_no": "DEMO-PAYOUT-001",
  "status": 20,
  "pay_time": "2026-10-05 17:02:00",
  "amount": "500.00",
  "total_fee": "10.00",
  "settlement_amount": "510.00",
  "created_at": "2026-10-05 17:00:00",
  "utr": "123456789012",
  "notify_remark": "demo-payout",
  "signature": "fb6ab8d2792b0249a5e19369466c7dd1"
}

回调示例 · cURL

下面的 cURL 用于测试回调接收地址。

curl --request POST 'https://merchant.example/webhooks/payout' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "tenant_id": "DEMO0001",
  "platform_order_no": "PRT202610051700DEMO0001",
  "tenant_order_no": "DEMO-PAYOUT-001",
  "status": 20,
  "pay_time": "2026-10-05 17:02:00",
  "amount": "500.00",
  "total_fee": "10.00",
  "settlement_amount": "510.00",
  "created_at": "2026-10-05 17:00:00",
  "utr": "123456789012",
  "notify_remark": "demo-payout",
  "signature": "fb6ab8d2792b0249a5e19369466c7dd1"
}'

失败回调示例

{
  "tenant_id": "DEMO0001",
  "platform_order_no": "PRT202610051700DEMO0001",
  "tenant_order_no": "DEMO-PAYOUT-001",
  "status": 40,
  "amount": "500.00",
  "total_fee": "10.00",
  "settlement_amount": "510.00",
  "created_at": "2026-10-05 17:00:00",
  "notify_remark": "demo-payout",
  "signature": "adf799e94bc2928ba3e2de63cae9fca9"
}

接收应答

返回 HTTP 200，正文为纯文本 success 或 ok。忽略大小写及首尾空白。仅 HTTP 200，或 JSON {"status":200}，不足以确认。当前也兼容 {"code":200,"message":"success"}、{"success":true}、{"isSucceed":true}、{"data":"OK"}；推荐使用明确的纯文本应答。

HTTP/1.1 200 OK
Content-Type: text/plain

success

发送与结果

回调是结果通知，不保证仅发送一次。失败重试有次数上限，同一订单的成功通知可能重复。20 表示成功；更正、过期和冲正见完整状态说明。通知失败不改变付款结果，可通过查单确认。