卡交易更新
交易回调、自动巡检或查询补录处理完成后发送,携带交易与卡片的公开 ID 及实际状态。
事件类型
| 事件 | 什么时候发 |
|---|---|
card.transaction.updated | 卡交易已接收或状态已更新 |
投递约定
- 我方向你配置的端点发
POST,application/json,超时 10 秒。 - 回任意 2xx 即视为收到。 非 2xx 或超时会按退避重投。
- 请求头四个:
content-type·z-signature·z-event-id·z-event-type。 - 按
z-event-id去重 —— 同一条事件可能到达多次。
没有金额、没有资产代码、没有卡号的任何片段、没有风控原因。这不是省字节 ——
webhook 端点是你的服务,我方没有办法保证它的传输与存储;
而 GET /v1/<资源>/{id} 那条路径上有 API Key、scope、
代理会员三层校验。要详情就拿 data.id 回查,
别指望从事件体里读出金额来记账。
逐条
card.transaction.updated
卡交易已接收或状态已更新正常交易回调、自动巡检或运营查询补录处理完成后发送。data.id 是交易列表中的 ctx_ 资源 ID,data.card_id 是 crd_ 卡片 ID;通过 GET /v1/cards/{id}/transactions 回查。authorized 表示已授权、待结算,不能按已结算处理。同一本地交易的相同快照使用相同 event_id,接收方须按 event_id 去重。沙盒交易模拟走相同处理流程,通知按沙盒环境投递。bank_fee 为银行手续费,zinfra_fee 为 zinfra 手续费(当前所有卡为 "0")。均为最小单位整数串,币种与精度分别为 fee_currency、fee_scale。这是交易累计费用快照,不是每次通知新增收费;授权费用可能在结算时更新。original_amount / original_currency 是上游交易原币原文;bill_amount 是卡本币账单(最小单位整数串,与列表同一套取值:已存结算额或授权占用,不现场折汇)。没有已知账单时省略 bill_amount。详情以 GET /v1/cards/{id}/transactions 为准。
{
"event_id": "evt_06a0d3fbbe074aa98809e2b90588b123",
"event_type": "card.transaction.updated",
"created_at": "2026-09-08T05:45:00Z",
"merchant_id": "acme",
"livemode": true,
"data": {
"object": "card_transaction",
"id": "ctx_11111111-2222-4333-8444-555555555555",
"card_id": "crd_aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
"external_member_id": "u_88123",
"status": "authorized",
"status_version": 1788846300000,
"bank_fee": "30000",
"zinfra_fee": "0",
"fee_currency": "USD",
"fee_scale": 6,
"original_amount": "8.0000",
"original_currency": "HKD",
"bill_amount": "1020000"
}
}验签
验签方式与所有事件一致,见 Webhook 概览; 可以用签名调试器逐字符比对签名串。