Card Transaction Updates
Emitted after a transaction callback, automatic reconciliation or query-based backfill is processed, with the public transaction and card IDs and their actual status.
Event Types
| Event | When Emitted |
|---|---|
card.transaction.updated | Card transaction received or its status updated |
Delivery Contract
- We send a
POSTrequest withapplication/jsonto your configured endpoint, with a 10-second timeout. - Any 2xx response acknowledges receipt. Non-2xx responses and timeouts trigger retries with backoff.
- Four request headers:
content-type·z-signature·z-event-id·z-event-type。 - Deduplicate by
z-event-id— the same event may be delivered more than once.
There are no amounts, asset codes, card number fragments or risk-control reasons. This is a security boundary: the webhook endpoint is your service, whose transport and storage we cannot guarantee.
The GET /v1/<resource>/{id} endpoint applies API key, scope and on-behalf-of checks. Fetch details using data.id;
do not use webhook payloads as the source of amounts for your ledger.
Event Details
card.transaction.updated
Card transaction received or its status updatedSent after processing a normal transaction callback, automatic reconciliation, or an operations query that backfills a record. data.id is the ctx_ resource ID from the transaction list; data.card_id is the crd_ card ID. Retrieve through GET /v1/cards/{id}/transactions. authorized means authorized and awaiting settlement; do not treat it as settled. Identical snapshots of the same local transaction use the same event_id; recipients must deduplicate by event_id. Sandbox transaction simulation uses the same processing flow, with notifications delivered in the sandbox environment. kind is the transaction type and direction is debit/credit/none/unknown. For the complete type and status list, see Card transactions, fees, and refunds. posted indicates principal posting, not whether fees have been collected; settlement_status is the settlement marker. updated_at is the snapshot update time; original_transaction_id (ctx_) is included when the original transaction can be linked on this card. bank_fee is the bank fee, bank_fee_return is the cumulative bank fee returned on this record, and zinfra_fee is the zinfra fee. All are integer strings in minor units, with currency and precision supplied by fee_currency and fee_scale. These are cumulative transaction fee snapshots, not additional fees charged for each notification; authorization fees may change at settlement. fee_paid/fee_due are the fee workflow’s current net paid/outstanding amounts. fee_state is none/reserved/processing/due/refunding/settled/review. Separate settlement and fee-return updates also trigger this event. original_amount / original_currency preserve the upstream transaction’s original currency and amount text. bill_amount is the card-currency bill amount, an integer string in minor units using the same source as the list: the stored settlement amount or authorization hold, without on-demand currency conversion. bill_amount is omitted when no bill amount is known. GET /v1/cards/{id}/transactions remains authoritative for details.
{
"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"
}
}Signature Verification
The signature verification procedure is the same for all events. See Webhook Overview; use the Signature Debugger to compare signing strings character by character.