订单级事件
这些事件基于支付订单的整体生命周期和状态变化触发。商户应严格依赖这些事件（特别是 pay.transaction）作为发货或放行服务的唯一权威凭证。
🔔 事件类型 (Event Types)
| 事件标识 (event_identifier) | 触发时机与业务含义 | 处理建议 |
|---|---|---|
pay.transaction | 订单创建 (Created)：当系统成功创建一笔支付订单时触发。此时状态通常为 pending。 | 仅用于记录或对账，切勿发货。 |
pay.transaction.update | 订单更新 (Updated)：当订单的状态、确认金额等发生任何变化时触发。 | 🌟 发货凭证：请监听此事件，当 Payload 中的 status 字段变为 completed 时，执行最终的发货/放行逻辑。 |
📦 Webhook 数据结构样例 (Payload Example)
当事件发生时，DogPay 会向您配置的 Webhook 端点发送 POST 请求。以下为 pay.transaction.update 触发且订单已完成时的完整样例：
{
"event_id": "997daf9b-4162-4864-914c-960ff6cc16ad",
"event_identifier": "pay.transaction.update",
"data": {
"id": "761ca541-df6e-4273-a3f2-e3df85e5c3b7",
"idNo": "1940644675780100097",
"transactionAt": "2025-07-03T05:32:00.796Z",
"completedAt": "2025-07-04T14:32:17.366Z",
"payType": "chain_address",
"payer": null,
"payChannel": "pay_001",
"status": "completed",
"amount": "0.02000000",
"usdAmount": "0.02000000",
"usdFeeAmount": "0.01000000",
"currency": "USDC",
"transactionId": "817f2df2-3b0e-472f-b40e-20ed4c24761c",
"accountId": "0721aeda-ed79-4398-887b-77fd225c69f4",
"fee": "0.01000000",
"totalAmount": "0.00000000",
"usdRate": "1.00000000",
"settleStatus": "unsettled",
"type": "pay",
"originPayOrderId": null,
"callId": "0f38a615-ec28-7866-351f-7fcb78862b7n",
"balanceId": "eb078bf9-82ad-4c00-bf6a-992632b55d21",
"cursorId": "375638181647749120",
"successUrl": "[https://api.string.com/url](https://api.string.com/url)",
"failureUrl": "[https://api.string.com/url](https://api.string.com/url)",
"extraData": {
"payType": "WEB",
"goodsName": "测试_V2"
},
"payChannelCurrencyId": "c4dff705-3012-4b91-a4f5-0a4ec8a4982f",
"waitAmountOnChain": "0",
"doneAmountOnChain": "0.02",
"receiveAddress": "0xB0a2821fAa9AD8c08D2764EAF85C414518137620"
}
}
幂等性提示 (Idempotency Note)
请使用 payload 中的event_id或订单的idNo作为防重凭证。在处理发货逻辑前，务必先查询您数据库中该订单是否已处于“已处理”状态，以防网络重试导致重复发货。
Updated about 13 hours ago