通过开放 API 创建的订单,状态变化(支付成功、过期、关闭、退款)时平台向 notify_url 发送 JSON POST。(易支付接口下单的订单仍按易支付 GET 格式通知。)
| 请求头 | 说明 |
|---|---|
X-AiPay-Event | 事件类型:order.paid(支付成功) / order.expired(超时未支付) / order.closed(主动关闭) / order.refunded(已退款) |
X-AiPay-Event-Id | 事件唯一 ID(如 evt_12_paid),同一事件重试时保持不变 |
X-AiPay-Timestamp | 发送时间(Unix 秒) |
X-AiPay-Nonce | 随机串 |
X-AiPay-Signature | hex(HMAC_SHA256(商户密钥, TIMESTAMP + "\n" + NONCE + "\n" + BODY)) |
{"event":"order.paid","event_id":"evt_12_paid","occurred_at":1791858489,"pid":1000,"data":{订单对象,不含 pay_url / qrcode_url}}data 是事件发生时的订单快照,重试时请求体保持不变(仅签名头的时间戳与随机串每次重新生成);occurred_at 为事件发生时间(Unix 秒)。
1. 用原始请求体校验签名(常量时间比较),并检查时间戳在 5 分钟内;
2. 以 event_id 幂等去重,同一事件可能因重试收到多次;
3. 处理成功后返回 HTTP 200 且响应体为 success,否则按 15s / 30s / 1m / 3m / 10m / 30m / 1h / 2h 重试,共 8 次;
4. 回调不跟随重定向,notify_url 不能是内网或本机地址;
5. 漏收回调时可调用 /api/v1/order/notify 手动重发,或用 /api/v1/order/notify_logs 排查;
6. 退款为仅记账语义:收到 order.refunded 后请自行线下向付款人原路退回资金;
7. 各事件独立投递、独立重试,不保证到达顺序。订单状态只会 pending → paid / closed / expired、paid → refunded;
若先收到 order.refunded 再收到同订单的 order.paid,后者只做幂等确认,不要把订单状态改回已支付(可用 occurred_at 判断先后)。