Z Zise Developers English
卡发行 › Webhook

卡交易更新

交易回调、自动巡检或查询补录处理完成后发送,携带交易与卡片的公开 ID 及实际状态。

事件类型

事件什么时候发
card.transaction.updated卡交易已接收或状态已更新

投递约定

事件体只带 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 概览; 可以用签名调试器逐字符比对签名串。