--- title: "Card transaction state change" method: POST path: "cards#transaction-state-change" tags: ["webhook-event", "card-transaction"] --- # Card transaction state change `POST cards#transaction-state-change` (webhook) 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. ## Headers - `X-Signature-SHA256` string - `X-Delivery-Id` string, uuid - `X-Test-Notification` boolean ## Payload - union - V40011 - `schema_version` '4.0.0' — Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook). - `subscription_id` string, uuid — ID of the webhook subscription that triggered this event. - `event_type` string — Event type identifier - `sent_at` string, date-time — Timestamp when the event was sent. - `data` object - `resource` object - `profile_id` integer — ID of the profile that owns the card. - `client_id` string — Your `api_client_id` - `card_token` string — Unique identifier of the card. - `card_last_digits` string — Last 4 digits of the card. - `type` string — Resource type (always `card`). - `transaction_id` integer — ID of the transaction. - `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. - `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. - `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. - `decline_reason` string, nullable — Code of the decline reason if applicable. - `detailed_decline_reason` string, nullable — Code of the detailed decline reason if applicable. See list of [card transaction decline reasons](/api-reference/card-transaction#card-transaction-detailed-decline-reasons). - `creation_time` string, date-time — When the transaction was created. - `occurred_at` string, date-time — When the transaction state change occurred. - `purge_time` string, date-time, nullable — Time at which reserved funds will be released after the authorisation hold expires. - `transaction_amount` object - `value` number — Transaction amount, excluding all embedded fees such as ATM fees that are not applied by Wise. - `currency` string — Currency code - `fees` object[] — Array of fees - `amount` number — Fee amount - `currency` string — Currency code - `fee_type` string — Fee type. Possible values: - `ATM_WITHDRAWAL` - Fee charged by Wise - `ATM_MACHINE` - Fee charged by the ATM owner - `transaction_amount_with_fees` object - `value` number — Transaction amount including all fees. - `currency` string — Currency code - `billing_amount` object - `value` number — Billing amount - `currency` string — Currency code - `merchant` object - `name` string — Name of the merchant. - `location` object - `country` string — Country where merchant is located. - `city` string — City where merchant is located. - `postCode` string, nullable — Post code where merchant is located. - `state` string, nullable — State where merchant is located. - `category` object - `code` string — Merchant category code - `description` string — Merchant category description - `authorisation_method` string — Authorisation method - `approval_code` string — Also called authorization code. This can be used to prove ownership of a customer's card/account to a merchant. - `arn` string, nullable — Acquirer reference number - `pin_validation_result` string — PIN validation result. Possible values: - `ONLINE_PIN_VALIDATED` - `ONLINE_PIN_INVALID` - `OFFLINE_PIN_VALIDATED` - `OFFLINE_PIN_INVALID` - `NOT_RECEIVED` - `balance_channel_reference_id` string — Balance channel reference ID associated with the card transaction. - `debits` object[] — 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. - `balance_id` integer — Balance ID - `debited_amount` object - `value` number — Amount taken from the balance. - `currency` string — Currency code - `for_amount` object - `value` number — Amount converted to - `currency` string — Currency code - `rate` number — Exchange rate - `fee` object - `value` number — Conversion fee amount - `currency` string — Currency code - `creation_time` string, date-time — Time of balance debit creation. - `credits` object[] — Array of credits - `balance_id` integer — Balance ID - `credited_amount` object - `value` number — Amount credited to the balance. - `currency` string — Currency code - `relay_authorisation_data` object - `response_code` string — Relayed authorisation [response code](/guides/product/issue-cards/relayed-authorisation#authorisation-response) - `fallback` boolean — Whether there was a fallback applied by Wise. - V210 - `schema_version` '2.1.0' — Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook). - `subscription_id` string, uuid — ID of the webhook subscription that triggered this event - `event_type` string — Event type identifier - `sent_at` string, date-time — Timestamp when the event was sent - `data` object - `resource` object - `profile_id` integer — ID of the profile that owns the card - `client_id` string — Your api_client_id - `card_token` string — Unique identifier of the card - `card_last_digits` string — Last 4 digits of the card - `type` string — Resource type (always `card`) - `transaction_id` integer — ID of the transaction - `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 - `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. - `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 - `decline_reason` string, nullable — Code of the decline reason if applicable - `detailed_decline_reason` string, nullable — Code of the detailed decline reason if applicable. List of available options is available [here](/api-reference/card-transaction#card-transaction-detailed-decline-reasons). - `creation_time` string, date-time — When the transaction was created - `occurred_at` string, date-time — When the transaction state change occurred - `purge_time` string, date-time, nullable — Time at which reserved funds will be released after the authorisation hold expires - `transaction_amount` object - `value` number — Transaction amount, excluding all embedded fees such as ATM fees that are not applied by Wise - `currency` string — Currency code - `fees` object[] — Array of fees - `amount` number — Fee amount - `currency` string — Currency code - `fee_type` string — Fee type. Possible values: - `ATM_WITHDRAWAL` - Fee charged by Wise - `ATM_MACHINE` - Fee charged by the ATM owner - `transaction_amount_with_fees` object - `value` number — Transaction amount including all fees - `currency` string — Currency code - `billing_amount` object - `value` number — Billing amount - `currency` string — Currency code - `merchant` object - `name` string — Name of the merchant - `location` object - `country` string — Country where merchant is located - `city` string — City where merchant is located - `postCode` string, nullable — Post code where merchant is located - `state` string, nullable — State where merchant is located - `category` object - `code` string — Merchant category code - `description` string — Merchant category description - `authorisation_method` string — Authorisation method - `approval_code` string — Also called authorization code. This can be used to prove ownership of a customer's card/account to a merchant - `arn` string, nullable — Acquirer reference number - `pin_validation_result` string — PIN validation result. Possible values: - `ONLINE_PIN_VALIDATED` - `ONLINE_PIN_INVALID` - `OFFLINE_PIN_VALIDATED` - `OFFLINE_PIN_INVALID` - `NOT_RECEIVED` - `balance_channel_reference_id` string — Balance channel reference ID associated with the card transaction - `debits` object[] — 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. - `balance_id` integer — Balance ID - `debited_amount` object - `value` number — Amount taken from the balance - `currency` string — Currency code - `for_amount` object - `value` number — Amount converted to - `currency` string — Currency code - `rate` number — Exchange rate - `fee` object - `value` number — Conversion fee amount - `currency` string — Currency code - `creation_time` string, date-time — Time of balance debit creation - `credits` object[] — Array of credits - `balance_id` integer — Balance ID - `credited_amount` object - `value` number — Amount credited to the balance - `currency` string — Currency code - `relay_authorisation_data` object - `response_code` string — Relayed authorisation [response code](/guides/product/issue-cards/relayed-authorisation#authorisation-response) - `fallback` boolean — Whether there was a fallback applied by Wise - V20011 - `schema_version` '2.0.0' — Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook). - `subscription_id` string, uuid — ID of the webhook subscription that triggered this event - `event_type` string — Event type identifier - `sent_at` string, date-time — Timestamp when the event was sent - `data` object - `resource` object - `profile_id` integer — ID of the profile that owns the card - `client_id` string — Your api_client_id - `card_token` string — Unique identifier of the card - `card_last_digits` string — Last 4 digits of the card - `type` string — Resource type (always `card`) - `transaction_id` integer — ID of the transaction - `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 - `is_debit` boolean — Indicates whether the transaction type is a debit. This field is deprecated, use `data.transaction_amount.value` to determine if the transaction is a debit (positive) or a credit into the balance (negative). - `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. - `decline_reason` string, nullable — Code of the decline reason if applicable - `detailed_decline_reason` string, nullable — Code of the detailed decline reason if applicable. List of available options is available [here](/api-reference/card-transaction#card-transaction-detailed-decline-reasons). - `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 - `transaction_amount` object - `value` number — Transaction amount, excluding all embedded fees such as ATM fees that are not applied by Wise - `currency` string — Currency code - `is_amount_confirmed` boolean — Whether the transaction amount is confirmed - `fees` object[] — Array of fees - `amount` number — Fee amount - `currency` string — Currency code - `fee_type` string — Fee type. Possible values: - `ATM_WITHDRAWAL` - Fee charged by Wise - `ATM_MACHINE` - Fee charged by the ATM owner - `transaction_amount_with_fees` object - `value` number — Transaction amount including fees - `currency` string — Currency code - `billing_amount` object - `value` number — Billing amount - `currency` string — Currency code - `authorisation_method` string — Authorisation method - `pin_validation_result` string — PIN validation result. Possible values: - `ONLINE_PIN_VALIDATED` - `ONLINE_PIN_INVALID` - `OFFLINE_PIN_VALIDATED` - `OFFLINE_PIN_INVALID` - `NOT_RECEIVED` - `approval_code` string — Also called authorization code. This can be used to prove ownership of a customer's card/account to a merchant - `purge_time` string, date-time, nullable — Time at which reserved funds will be released after the authorisation hold expires - `balance_transaction_id` integer — Associated balance transaction id if applicable - `balance_movements` object[] — Array of balance movements - `creation_time` string, date-time — When the balance movement occurred - `balance_id` string — ID of the balance credited or debited - `type` string — `credit` or `debit` - `amount` object - `value` number — Credited or debited amount - `currency` string — Currency code - `debits` object[] — Array of debits - `balance_id` integer — Balance ID - `debited_amount` object - `value` number — Amount taken from the balance - `currency` string — Currency code - `for_amount` object - `value` number — Amount converted to - `currency` string — Currency code - `rate` number — Exchange rate - `fee` object - `value` number — Conversion fee amount - `currency` string — Currency code - `credit` object, nullable - `balance_id` integer — Balance ID - `credited_amount` object - `value` number — Amount credited to the balance - `currency` string — Currency code - `merchant` object - `name` string — Name of the merchant - `location` object - `country` string — Country where merchant is located - `city` string — City where merchant is located - `postCode` string, nullable — Post code where merchant is located - `state` string, nullable — State where merchant is located - `category` object - `code` string — Merchant category code - `description` string — Merchant category description - `arn` string, nullable — Acquirer reference number - `creation_time` string, date-time — When transaction was created - `occurred_at` string, date-time — When transaction or transaction state change occurred - `relay_authorisation_data` object - `response_code` string — Relayed authorisation [response code](/guides/product/issue-cards/relayed-authorisation#authorisation-response) - `fallback` boolean — Whether there was a fallback applied by Wise ## Acknowledgement `200` Return any `2xx` status to acknowledge receipt of the event. - object - `status` string --- [API](https://skmtc.net/wise/apis/platform-api.md) · [All operations](https://skmtc.net/wise/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/wise/platform-api/revisions/4907a1d269ab/schema)