异步通知
平台向创建请求保存的 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