card.transaction.updated
卡交易已接收或状态已更新
何时发
正常交易回调、自动巡检或运营查询补录处理完成后发送。 data.id 是交易列表中的 ctx_ 资源 ID, data.card_id 是 crd_ 卡片 ID;通过 GET /v1/cards/{id}/transactions 回查。 authorized 表示已授权、待结算,不能按已结算处理。 同一本地交易的相同快照使用相同 event_id,接收方须按 event_id 去重。 沙盒交易模拟走相同处理流程,通知按沙盒环境投递。 kind 为交易类型,direction 为 debit/credit/none/unknown;完整类型与状态清单见 卡交易、手续费与退款。 posted 表示本金是否过账,不代表费用是否已收;settlement_status 为结算标记。 updated_at 为快照更新时间;能关联到本卡原交易时返回 original_transaction_id(ctx_)。 bank_fee 为银行手续费,bank_fee_return 为本条记录累计银行手续费返还,zinfra_fee 为 zinfra 手续费。 均为最小单位整数串,币种与精度分别为 fee_currency、fee_scale。 这是交易累计费用快照,不是每次通知新增收费;授权费用可能在结算时更新。 fee_paid/fee_due 为费用流程当前已收净额/待收额,fee_state 为 none/reserved/processing/due/refunding/settled/review。独立结算及费用返还也会触发本事件。 original_amount / original_currency 是上游交易原币原文;bill_amount 是卡本币 账单(最小单位整数串,与列表同一套取值:已存结算额或授权占用,不现场折汇)。 没有已知账单时省略 bill_amount。详情以 GET /v1/cards/{id}/transactions 为准。
由 cron 或上游回调触发。
事件体
{
"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",
"kind": "auth",
"direction": "debit",
"posted": false,
"settlement_status": "Unsettled",
"updated_at": "2026-09-08T05:45:00Z",
"currency": "USD",
"scale": 6,
"status_version": 1788846300000,
"bank_fee": "30000",
"bank_fee_return": "0",
"zinfra_fee": "0",
"fee_paid": "0",
"fee_due": "0",
"fee_state": "none",
"fee_currency": "USD",
"fee_scale": 6,
"original_amount": "8.0000",
"original_currency": "HKD",
"bill_amount": "1020000"
}
}
事件体字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 去重用这个。evt_…,同一事件重投时不变。 |
type | string | 固定为 card.transaction.updated |
created_at | string | 事件产生时刻(RFC3339)。不是投递时刻 —— 重投时它不变。 |
data.object | string | 对象类型,决定 data.id 该拿去查哪个端点 |
data.id | string | 对象 ID,拿它回查详情 |
data.status | string | 认不出的值按未知处理并告警,不要 fallback 成「处理中」 |
data.status_version | number | 单调递增,用它把慢到的旧状态丢掉 |
验签与去重
验签用原始请求体字节,不要先解析再重新序列化 —— 你的 JSON 库与我方的键顺序、空格几乎一定不同,重新序列化出来的签名一定对不上, 而那个错误长得像「密钥配错了」。
// Node · 放在解析 JSON 之前
const raw = await readRawBody(req); // Buffer / string,别用已解析的 req.body
const expect = crypto.createHmac("sha256", WEBHOOK_SECRET).update(raw).digest("hex");
const got = req.headers["z-signature"]; // 形如 t=<unix>,v1=<hex>
if (!timingSafeEqual(expect, parseV1(got))) return res.status(400).end();
// 去重:用信封的 id,不是 data.id
if (await seen(JSON.parse(raw).id)) return res.status(200).end();
完整做法(含时间戳容差与重投语义)见 Webhook 指南。