# Card transaction state change

Triggered whenever a new card transaction occurs or is modified.
* Event type: `cards#transaction-state-change`
* Profile level subscriptions: Not Supported
* Application level subscriptions: Supported

#### Transaction categorisation
Transactions can be categorized based on the guidelines below, though the results may not always be consistent.
* Active card check: `transaction_amount` is 0 or 1 and `merchant.category.code` does not equal `6011`.
* ATM balance check: `transaction_amount` is 0 and `merchant.category.code` equals `6011`.
* Pre-Authorisation: `is_amount_confirmed` is false and `transaction_state` equals `IN_PROGRESS`.

Events may not be delivered in the order they occurred. Use `data.occurred_at` to reconcile the order.
See the [Event ordering guide](/guides/developer/webhooks/event-ordering) for details.
See the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.

Endpoint: POST cards#transaction-state-change

## Header parameters:

  - `X-Signature-SHA256` (string)
    RSA-SHA256 signature of the request body, Base64 encoded. Verify this against the [Wise public key](/guides/developer/webhooks/event-handling#requests) to ensure the request is authentic and has not been tampered with.

  - `X-Delivery-Id` (string)
    Unique identifier for this webhook delivery attempt.

  - `X-Test-Notification` (boolean)
    Present with the value `true` if this is a test notification sent to verify your callback URL during subscription setup.

## Request fields (application/json):

  - `schema_version` (string)
    Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).
    Enum: "4.0.0"

  - `subscription_id` (string)
    ID of the webhook subscription that triggered this event.
    Example: 568da36b-7335-4608-ad1b-e5c2d32273b6

  - `event_type` (string)
    Event type identifier
    Example: cards#transaction-state-change

  - `sent_at` (string)
    Timestamp when the event was sent.
    Example: 2022-08-15T11:10:46.123Z

  - `data` (object)

  - `data.resource` (object)

  - `data.resource.profile_id` (integer)
    ID of the profile that owns the card.
    Example: 123456

  - `data.resource.client_id` (string)
    Your `api_client_id`
    Example: your-bank

  - `data.resource.card_token` (string)
    Unique identifier of the card.
    Example: 136b29e4-7eab-4dac-a017-438d494ef6cb

  - `data.resource.card_last_digits` (string)
    Last 4 digits of the card.
    Example: 1234

  - `data.resource.type` (string)
    Resource type (always `card`).
    Example: card

  - `data.transaction_id` (integer)
    ID of the transaction.
    Example: 12345

  - `data.transaction_type` (string)
    Type of the transaction. Possible values:
- `ACCOUNT_CREDIT` - Receiving money on the card, excluding Visa OCT or Mastercard MoneySend.
- `ACCOUNT_FUNDING` - Sending money to another card or e-wallet.
- `CASH_ADVANCE` - Cash disbursement.
- `CASH_WITHDRAWAL` - ATM withdrawal.
- `CHARGEBACK` - Currently unused. Reserved for future use.
- `CREDIT_TRANSACTION` - Visa OCT and Mastercard MoneySend.
- `ECOM_PURCHASE` - Online purchase.
- `POS_PURCHASE` - Purchase via a POS terminal.
- `REFUND` - Partial or full refund of an existing card transaction.
    Example: CASH_WITHDRAWAL

  - `data.transaction_step_type` (string)
    Step type of the transaction. Possible values:
- `AUTH` - Transaction authorization which is usually the first step.
- `PARTIAL_REVERSAL` - Transaction has been partially reversed.
- `FULL_REVERSAL` - Transaction has been fully reversed.
- `CAPTURE` - Transaction has been captured.
- `SETTLE` - Currently unused. Reserved for future use.
- `REFUND` - Currently unused. Reserved for future use.
- `RECONCILIATION` - Currently unused. Reserved for future use.
    Example: CAPTURE

  - `data.transaction_state` (string)
    The current state of the transaction. Possible values:
- `IN_PROGRESS` - The transaction is still in progress.
- `COMPLETED` - The transaction is completed.
- `DECLINED` - The transaction has been declined.
- `CANCELLED` - The transaction has been cancelled.
- `UNKNOWN` - Default fallback status.
    Example: COMPLETED

  - `data.decline_reason` (string | null)
    Code of the decline reason if applicable.
    Example: null

  - `data.detailed_decline_reason` (string | null)
    Code of the detailed decline reason if applicable. See list of [card transaction decline reasons](/api-reference/card-transaction#card-transaction-detailed-decline-reasons).
    Example: null

  - `data.creation_time` (string)
    When the transaction was created.
    Example: 2022-08-15T11:10:41.456Z

  - `data.occurred_at` (string)
    When the transaction state change occurred.
    Example: 2022-08-15T11:10:41.789Z

  - `data.purge_time` (string | null)
    Time at which reserved funds will be released after the authorisation hold expires.
    Example: 2022-08-22T11:10:41.123Z

  - `data.transaction_amount` (object)

  - `data.transaction_amount.value` (number)
    Transaction amount, excluding all embedded fees such as ATM fees that are not applied by Wise.
    Example: 100

  - `data.transaction_amount.currency` (string)
    Currency code
    Example: EUR

  - `data.fees` (array)
    Array of fees

  - `data.fees.amount` (number)
    Fee amount
    Example: 1

  - `data.fees.currency` (string)
    Currency code
    Example: EUR

  - `data.fees.fee_type` (string)
    Fee type. Possible values:
- `ATM_WITHDRAWAL` - Fee charged by Wise
- `ATM_MACHINE` - Fee charged by the ATM owner
    Example: ATM_WITHDRAWAL

  - `data.transaction_amount_with_fees` (object)

  - `data.transaction_amount_with_fees.value` (number)
    Transaction amount including all fees.
    Example: 101

  - `data.transaction_amount_with_fees.currency` (string)
    Currency code
    Example: EUR

  - `data.billing_amount` (object)

  - `data.billing_amount.value` (number)
    Billing amount
    Example: 100

  - `data.billing_amount.currency` (string)
    Currency code
    Example: EUR

  - `data.merchant` (object)

  - `data.merchant.name` (string)
    Name of the merchant.
    Example: Test Payment

  - `data.merchant.location` (object)

  - `data.merchant.location.country` (string)
    Country where merchant is located.
    Example: France

  - `data.merchant.location.city` (string)
    City where merchant is located.
    Example: Rouen

  - `data.merchant.location.postCode` (string | null)
    Post code where merchant is located.
    Example: 00000

  - `data.merchant.location.state` (string | null)
    State where merchant is located.
    Example: null

  - `data.merchant.category` (object)

  - `data.merchant.category.code` (string)
    Merchant category code
    Example: 5999

  - `data.merchant.category.description` (string)
    Merchant category description
    Example: 5999 R Miscellaneous and Special

  - `data.authorisation_method` (string)
    Authorisation method
    Example: MANUAL_ENTRY

  - `data.approval_code` (string)
    Also called authorization code. This can be used to prove ownership of a customer's card/account to a merchant.
    Example: 913647

  - `data.arn` (string | null)
    Acquirer reference number
    Example: 04300014127798385983852

  - `data.pin_validation_result` (string)
    PIN validation result. Possible values:
- `ONLINE_PIN_VALIDATED`
- `ONLINE_PIN_INVALID`
- `OFFLINE_PIN_VALIDATED`
- `OFFLINE_PIN_INVALID`
- `NOT_RECEIVED`
    Example: ONLINE_PIN_VALIDATED

  - `data.balance_channel_reference_id` (string)
    Balance channel reference ID associated with the card transaction.
    Example: 6e71018d-2f4d-4fc3-6711-f517f4664712

  - `data.debits` (array)
    Array of debits. Note that the debits list is a non-aggregated list of debit movements, meaning that the `balance_id` is not unique in the list. For example, a cancelled transaction may have a list of 2 debits where the absolute values of `debited_amount.value`, `for_amount.value` and `fee.value` are the same, but one is the negation of the other due to a reservation (first debit) which was then released (second debit with negated amounts). In this case, you can choose to perform the aggregation in your system or display the full list of debits to the end customer.

  - `data.debits.balance_id` (integer)
    Balance ID
    Example: 123

  - `data.debits.debited_amount` (object)

  - `data.debits.debited_amount.value` (number)
    Amount taken from the balance.
    Example: 165.96

  - `data.debits.debited_amount.currency` (string)
    Currency code
    Example: AUD

  - `data.debits.for_amount` (object)

  - `data.debits.for_amount.value` (number)
    Amount converted to
    Example: 101

  - `data.debits.for_amount.currency` (string)
    Currency code
    Example: EUR

  - `data.debits.rate` (number)
    Exchange rate
    Example: 0.61223252

  - `data.debits.fee` (object)

  - `data.debits.fee.value` (number)
    Conversion fee amount
    Example: 0.99

  - `data.debits.fee.currency` (string)
    Currency code
    Example: AUD

  - `data.debits.creation_time` (string)
    Time of balance debit creation.
    Example: 2022-08-15T11:10:41.456Z

  - `data.credits` (array)
    Array of credits

  - `data.credits.balance_id` (integer)
    Balance ID
    Example: 123

  - `data.credits.credited_amount` (object)

  - `data.credits.credited_amount.value` (number)
    Amount credited to the balance.
    Example: 100

  - `data.credits.credited_amount.currency` (string)
    Currency code
    Example: EUR

  - `data.relay_authorisation_data` (object)

  - `data.relay_authorisation_data.response_code` (string)
    Relayed authorisation [response code](/guides/product/issue-cards/relayed-authorisation#authorisation-response)
    Example: APPROVED

  - `data.relay_authorisation_data.fallback` (boolean)
    Whether there was a fallback applied by Wise.
    Example: true

  - `subscription_id` (string)
    ID of the webhook subscription that triggered this event
    Example: 568da36b-7335-4608-ad1b-e5c2d32273b6

  - `sent_at` (string)
    Timestamp when the event was sent
    Example: 2026-02-02T11:05:20Z

## Response 200 fields (application/json):

  - `status` (string)
    Example: ok