汇款订单状态

一笔汇款到达终局时发送：完成、失败、或已退款。

事件类型

事件	什么时候发
`remittance.order.completed`	汇款已到账收款人
`remittance.order.failed`	汇款未能完成，冻结资金已全额退回
`remittance.order.refunded`	汇款到账后被收款行退回，款项已退回会员余额

投递约定

我方向你配置的端点发 POST，application/json，超时 10 秒。
回任意 2xx 即视为收到。 非 2xx 或超时会按退避重投。
请求头四个：content-type · z-signature · z-event-id · z-event-type。
按 z-event-id 去重 —— 同一条事件可能到达多次。

事件体只带 ID 与状态

没有金额、没有资产代码、没有卡号的任何片段、没有风控原因。这不是省字节 —— webhook 端点是你的服务，我方没有办法保证它的传输与存储；而 GET /v1/<资源>/{id} 那条路径上有 API Key、scope、代理会员三层校验。要详情就拿 data.id 回查， 别指望从事件体里读出金额来记账。

逐条

remittance.order.completed 汇款已到账收款人

什么时候发

上游回报该笔 payout 完成、我方结算凭证落账那一刻。这是终态。

事件体

{
  "event_id": "evt_3ad9165e7b0c4f82a91d64c05e73b8f1",
  "event_type": "remittance.order.completed",
  "created_at": "2026-08-12T14:20:08Z",
  "merchant_id": "acme",
  "livemode": true,
  "data": {
    "object": "remittance",
    "id": "1c0e8a37-45bd-4f6a-b2e1-90a7d3f5c862",
    "external_member_id": "u_88123",
    "status": "completed",
    "status_version": 6
  }
}

remittance.order.failed 汇款未能完成，冻结资金已全额退回

什么时候发

上游拒付、合规拒绝、或建收款人失败等导致这一单走不下去。钱已经回到会员可用余额了 —— 你的客服话术要说清这一点，只说「失败」会立刻换来一通「那我的钱呢」。

事件体

{
  "event_id": "evt_86f4c1097d2b4e35a8c0136be59d7f20",
  "event_type": "remittance.order.failed",
  "created_at": "2026-08-12T14:31:44Z",
  "merchant_id": "acme",
  "livemode": true,
  "data": {
    "object": "remittance",
    "id": "1c0e8a37-45bd-4f6a-b2e1-90a7d3f5c862",
    "external_member_id": "u_88123",
    "status": "failed",
    "status_version": 5
  }
}

remittance.order.refunded 汇款到账后被收款行退回，款项已退回会员余额

什么时候发

与 failed 刻意分开：这一单曾经发过 completed，你的用户看到过「已到账」。合并成 failed 会让他以为之前那条是误报。

事件体

{
  "event_id": "evt_e29a704c6b3d418f95720ad3c8f16b54",
  "event_type": "remittance.order.refunded",
  "created_at": "2026-08-13T09:02:31Z",
  "merchant_id": "acme",
  "livemode": true,
  "data": {
    "object": "remittance",
    "id": "1c0e8a37-45bd-4f6a-b2e1-90a7d3f5c862",
    "external_member_id": "u_88123",
    "status": "refunded",
    "status_version": 8
  }
}

验签

验签方式与所有事件一致，见 Webhook 概览；可以用签名调试器逐字符比对签名串。