Z Zise Developers 简体中文
Card Issuance › Webhook

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

EventWhen Emitted
card.transaction.updatedCard transaction received or its status updated

Delivery Contract

Event payloads contain only IDs and status

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 updated
When Emitted

Sent 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.

Payload
{
  "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.