Webhooks
Webhooks are also provided to give you notifications on customer activities.
All webhook event notification payloads have the same high-level structure. Top-level properties are common to all events. The data
property is an object that can contain various properties. The exact properties that the data
object contains depends on the event type and schema version of the event.
Event type- and schema version-specific details
ID of the webhook subscription that triggered the event notification
Event type (what event happened in our system)
Schema version (what notification structure is being used to model the event)
When the event notification was sent from our system
{"data": {},"subscription_id": "01234567-89ab-cdef-0123-456789abcdef","event_type": "event#type","schema_version": "2.0.0","sent_at": "2020-01-01T12:34:56Z"}
- Event type:
cards#card-order-status-change
- Profile level subscriptions: Not Supported
- Application level subscriptions: Supported
This event will be triggered every time a card order status is updated. Please note that statuses depend on the type of card (virtual/physical). Additional statuses related to delivery exist for physical cards.
ID of the profile that owns the card
Webhook notification of type 'card'
Api client_id
Unique identifier of the card
Card order ID associated with the status change
Updated card order status
Delivery vendor used to dispatch the order (physical card only)
When the card order status change occurred
{"data":{"resource":{"type": "card","profile_id": "123456","client_id": "your-bank","card_token": "35050a4a-9521-426e-8109-1396e3687a3e","card_program": "VISA_DEBIT_CONSUMER_UK_1_PHYSICAL_CARDS_API"},"order_id" : "1001L","order_status": "PRODUCED","delivery_vendor": "DHL","occurred_at":"2023-01-01T12:24:56Z"},"subscription_id":"01234567-89ab-cdef-0123-456789abcdef","event_type":"cards#card-order-status-change","schema_version":"2.0.0","sent_at":"2023-01-01T12:34:56Z"}
Table of available card order status and description
The initial status is PLACED
or REQUIREMENT_FULFILLED
depending on the requirement fulfillment state.
The possible values are shown in the table below:
Status | Definition |
---|---|
PLACED | The card order is created. The card will be generated once it has fulfilled all the requirements |
REQUIREMENTS_FULFILLED | The card order has fulfilled all the requirements and the card should be generated in a short while |
CARD_DETAILS_CREATED | The card has been generated |
PRODUCED | The physical card has been produced and waiting to be picked up by delivery vendor (physical card only) |
COMPLETED | The card has been activated and is ready to use. The card order is completed |
CANCELLED | The card order has been cancelled. This can happen if you reach out to Wise Support to cancel a card order |
RETURNED | Delivery failed, the physical card has been returned and will be blocked (physical card only) |
![Create card order statuses transition diagram](/staticrab/api-documentation/diagrams/card-order-status-flow.png)
- Event type:
cards#card-status-change
- Profile level subscriptions: Not Supported
- Application level subscriptions: Supported
This event will be triggered every time a card status is updated or changed.
ID of the profile that owns the card
Your api_client_id
Unique identifier of the card
Resource type (always card
)
The updated card status
When the card status change occurred
Table of available card status and descriptions
Code | Description |
---|---|
ACTIVE | Card is active and can be used |
INACTIVE | Physical card has not been activated |
BLOCKED | Card is blocked and cannot be reversed back to any state |
FROZEN | Card is “blocked” but temporarily |
PARTNER_SUSPENDED | Card is suspended by Wise temporarily due to e.g. fraud reasons |
EXPIRED | Card is expired |
PURGED | The cardhoder data (e.g. PAN, PIN) have been purged after exceeds the retention period (555 days after the card's expiry date) |
{"data": {"resource": {"profile_id": 123456,"client_id": "your-bank","card_token": "ABCD-1234-ABCD-1234-ABCD","type": "card"},"card_status": "FROZEN","occurred_at": "2022-08-22T07:49:50Z",},"subscription_id": "ABCD-1234-ABCD-1234-ABCD","event_type": "cards#card-status-change","schema_version": "2.0.0","sent_at": "2022-08-22T07:59:50Z"}
- Event type:
cards#transaction-state-change
- Profile level subscriptions: Not Supported
- Application level subscriptions: Supported
This event will be triggered whenever a new card transaction occurs or is modified.
Although it is possible to interpret some transactions using the transaction fields, they are not always guaranteed. For example, some merchants may choose to do active card checks with a transaction_amount of 1
- active card check –
transaction_amount
is 0 andmerchant.category.code
not equals6011
- ATM balance check –
transaction_amount
is 0 andmerchant.category.code
equals6011
- Pre-Authorisation –
is_amount_confirmed
is false andtransaction_state
equalsIN_PROGRESS
ID of the profile that owns the card
Your api_client_id
Unique identifier of the card
Last 4 digits of the card
Resource type (always card
)
ID of the transaction
Type of the transaction
Whether it is a debit transaction
Step type of the transaction
Code of the decline reason if applicable
The current state of the transaction
Transaction amount
Currency code
Whether the transaction amount is confirmed
Fee amount
Currency code
Fee type
Transaction amount including fees
Currency code
Billing amount
Currency code
Authorisation method
Associated balance transaction id if applicable
Balance ID
Amount taken from the balance
Currency code
Amount converted to
Currency code
Exchange rate
Conversion fee amount
Currency code
Balance ID
Amount credited to the balance
Currency code
Merchant category code
Merchant category description
Acquirer reference number
When transaction was created
When transaction or transaction state change occurred
Table of available transaction state and descriptions
Code | Description |
---|---|
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 |
Table of available transaction type and descriptions
Code | Description |
---|---|
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 |
Table of available transaction step type and descriptions
Code | Description |
---|---|
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 caputured |
SETTLE | Currently unused. Reserved for future use. |
REFUND | Currently unused. Reserved for future use. |
RECONCILIATION | Currently unused. Reserved for future use. |
Table of available fee type and descriptions
Code | Description |
---|---|
ATM_WITHDRAWAL | Fee charged by Wise |
ATM_MACHINE | Fee charged by the ATM owner |
{"data": {"resource": {"profile_id": 123456,"client_id": "your-bank","card_token": "ABCD-1234-ABCD-1234-ABCD","card_last_digits": "1234","type": "card"},"transaction_id": 12345,"transaction_type": "CASH_WITHDRAWAL","is_debit": true,"transaction_step_type": "AUTH","decline_reason": null,"transaction_state": "IN_PROGRESS","transaction_amount": {"value": 100.00,"currency": "EUR"},"is_amount_confirmed": true,"fees": [{"amount": 1.00,"currency": "EUR","fee_type": "ATM_WITHDRAWAL"}],"transaction_amount_with_fees": {"value": 101.00,"currency": "EUR"},"billing_amount": {"value": 100.00,"currency": "EUR"},"authorisation_method": "CHIP_AND_PIN","balance_transaction_id": 12345,"debits": [{"balance_id": 123,"debited_amount": {"value": 165.96,"currency": "AUD"},"for_amount": {"value": 101.00,"currency": "EUR"},"rate": 0.61223252,"fee": {"value": 0.99,"currency": "AUD"}}],"credit": null,"merchant": {"category": {"code": "6011","description": "6011 Z Member Financial Institut"}},"arn": "04300014127798385983852","creation_time": "2022-08-15T11:10:41Z","occurred_at": "2022-08-15T11:10:41Z"},"subscription_id": "ABCD-1234-ABCD-1234-ABCD","event_type": "cards#transaction-state-change","schema_version": "2.0.0","sent_at": "2022-08-22T07:59:50Z"}
- Event type:
transaction-disputes#update
- Profile level subscriptions: Not Supported
- Application level subscriptions: Supported
This event will be triggered every time a transaction dispute is submitted or updated.
Unique ID of the dispute
ID of the profile that owns the card
ID of the card transaction
Resource type (always transaction-dispute
)
Dispute reason, you can find all the possible values here
Dispute overall status, it is either ACTIVE or CLOSED
Dispute detailed status, you can find all the possible values here
Explanation for subStatus
Time when the dispute was created
Creator of the dispute, it is currently set to the user id
Whether the dispute can be withdrawn
When the dispute updates occurred
{"data": {"resource": {"id": "39f893e3-4b0c-4850-9c5c-8cb8f4798a43","profile_id": 16605997,"transaction_id": 4337,"type": "transaction-dispute"},"reason": "WRONG_AMOUNT","status": "CLOSED","sub_status": "WITHDRAWN","status_message": "Withdrawn","created_at": "2024-04-18T06:17:12Z","created_by": "6097861","can_withdraw": false,"occurred_at": "2024-04-18T06:36:15Z"},"event_type": "transaction-disputes#update","schema_version": "2.0.0","sent_at": "2024-04-18T06:36:17Z","subscription_id": "7bb32a11-74ad-43b6-9505-3f5facbc87ed"}