文档目录 · 异步通知

异步通知

平台向创建请求保存的 notify_url 发送 JSON 通知;未传时使用商户默认通知地址,均未配置时不发送。

通道维护不阻断已有正式订单接收交易结果及发送异步通知;商户继续按原验签、去重和应答规则处理,无新增维护通知事件。

字段 类型 说明
event_type、status string 通知事件和交易状态,见下表
platform_order_no、merchant_order_no string 平台与商户订单号
amount、currency string 交易金额与币种
completed_at string 事件完成时间,RFC 3339
timestamp integer 通知发送时间,Unix 秒
nonce string 本次通知的随机串
secret_version integer 签名使用的 Secret 版本
sign string 64 位小写 HMAC-SHA256 签名

正式订单通知另含 channel_code 和 channel_order_no。正式代收通知包含订单锁定的 fee_amount、net_amount;代收成功另含 paid_amount、paid_at。失败或过期通知中的费用和净额只表示订单费率快照,不表示已经入账。代付通知包含 fee_amount、net_amount,其中 net_amount = amount + fee_amount。会话过期通知的附加字段见 6.2 节。

通知事件#

event_type status 含义
payin.succeeded paid 代收成功
payin.failed failed 代收失败
payin.expired expired 正式代收订单过期
payout.succeeded success 代付成功
payout.failed failed 代付失败
cashier.payin.expired expired 未生成正式代收订单的会话过期
cashier.payout.expired expired 未选通道且未提交的代付会话过期

代收成功示例:

{
  "event_type": "payin.succeeded",
  "platform_order_no": "P202609160001",
  "merchant_order_no": "PAY202609160001",
  "channel_order_no": "CHANNEL123456",
  "channel_code": "PAY_CHANNEL",
  "amount": "10.00",
  "fee_amount": "0.15",
  "net_amount": "9.85",
  "paid_amount": "10.00",
  "currency": "MYR",
  "status": "paid",
  "completed_at": "2026-09-16T15:12:38Z",
  "paid_at": "2026-09-16T15:12:38Z",
  "timestamp": 1789517558,
  "nonce": "notify-550e8400-e29b-41d4-a716-446655440000",
  "secret_version": 1,
  "sign": "<64位小写HMAC-SHA256>"
}

payin.expired 不含 paid_amount 或 paid_at,正式订单超时过期时含 reason_code=order_timeout。manual_review 后仍可能收到成功通知,应允许更新状态并避免重复记账。代付通知不含完整收款账号。

会话过期通知#

{
  "event_type": "cashier.payin.expired",
  "checkout_mode": "cashier",
  "platform_order_no": "P202609170001",
  "merchant_order_no": "PAY202609170001",
  "amount": "50.00",
  "currency": "MYR",
  "status": "expired",
  "reason_code": "cashier_channel_not_selected",
  "expired_at": "2026-09-17T08:30:00Z",
  "completed_at": "2026-09-17T08:30:00Z",
  "timestamp": 1789633800,
  "nonce": "notify-cashier-expired-001",
  "secret_version": 1,
  "sign": "<64位小写HMAC-SHA256>"
}

两类会话过期通知均含 checkout_mode=cashier,expired_at 与 completed_at 相同,不含正式通道、手续费、冻结金额或实付信息;已生成正式订单的会话按正式订单状态处理。

字段 类型 说明
reason_code string cashier_channel_not_selected(未选通道)或 cashier_submission_timeout(提交超时);接收端须支持两个值
expiry_revision string 可选正整数字符串,如 "2";缺省按版本 0,参与签名

同一会话可能收到不同版本的过期通知。不同版本分别处理,版本用于区分会话通知,不代表付款次数或资金流水。

验签、去重与应答#

通知验签算法与请求签名相同,须包含全部非空字段,并校验时间窗口、订单号、金额、币种和状态。secret_version 表示签名使用的 Secret 版本。

通知类型 去重键
普通正式订单通知 event_type + platform_order_no
状态更正通知 event_type + platform_order_no + status_revision
会话过期通知 event_type + platform_order_no + expiry_revision(缺省 0)

状态更正通知额外包含 status_revision(正整数字符串)和 correction="true",均参与签名;普通通知不含这两个字段。保存已处理的最高版本,避免旧版本覆盖新状态。更正可能为成功转失败或失败转成功,订单与账务须在同一业务事务中处理,不能将每条成功通知都作为新增入账。

处理成功后返回 HTTP 2xx,正文去除首尾空白后严格等于 SUCCESS;其他响应可能触发重试。重复通知也应返回成功应答。

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

SUCCESS

搜索文档