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.

Common Properties
dataobject

Event type- and schema version-specific details

subscription_idtext

ID of the webhook subscription that triggered the event notification

event_typestring

Event type (what event happened in our system)

schema_versionstring

Schema version (what notification structure is being used to model the event)

sent_atdatetime

When the event notification was sent from our system

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

Schema
data.resource.profile_idinteger

ID of the profile that owns the card

data.resource.typestring

Webhook notification of type 'card'

data.resource.client_idstring

Api client_id

data.resource.card_tokenstring or null

Unique identifier of the card

data.order_idstring

Card order ID associated with the status change

data.order_statusstring

Updated card order status

data.delivery_vendorstring or null

Delivery vendor used to dispatch the order (physical card only)

data.occurred_atdatetime

When the card order status change occurred

Example `cards#card-order-status-change` event
{
"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:

StatusDefinition
PLACEDThe card order is created. The card will be generated once it has fulfilled all the requirements
REQUIREMENTS_FULFILLEDThe card order has fulfilled all the requirements and the card should be generated in a short while
CARD_DETAILS_CREATEDThe card has been generated
PRODUCEDThe physical card has been produced and waiting to be picked up by delivery vendor (physical card only)
COMPLETEDThe card has been activated and is ready to use. The card order is completed
CANCELLEDThe card order has been cancelled. This can happen if you reach out to Wise Support to cancel a card order
RETURNEDDelivery failed, the physical card has been returned and will be blocked (physical card only)
Card order status transitions
Create card order statuses transition diagram
  • 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.

Schema
data.resource.profile_idinteger

ID of the profile that owns the card

data.resource.client_idstring

Your api_client_id

data.resource.card_tokenstring

Unique identifier of the card

data.resource.typestring

Resource type (always card)

data.card_statusstring

The updated card status

data.occurred_atdatetime

When the card status change occurred

Table of available card status and descriptions

CodeDescription
ACTIVECard is active and can be used
INACTIVEPhysical card has not been activated
BLOCKEDCard is blocked and cannot be reversed back to any state
FROZENCard is “blocked” but temporarily
PARTNER_SUSPENDEDCard is suspended by Wise temporarily due to e.g. fraud reasons
EXPIREDCard is expired
PURGEDThe cardhoder data (e.g. PAN, PIN) have been purged after exceeds the retention period (555 days after the card's expiry date)
Example `cards#card-status-change` event
{
"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 checktransaction_amount is 0 and merchant.category.code not equals 6011
  • ATM balance checktransaction_amount is 0 and merchant.category.code equals 6011
  • Pre-Authorisationis_amount_confirmed is false and transaction_state equals IN_PROGRESS
Schema
data.resource.profile_idinteger

ID of the profile that owns the card

data.resource.client_idstring

Your api_client_id

data.resource.card_tokenstring

Unique identifier of the card

data.resource.card_last_digitsstring

Last 4 digits of the card

data.resource.typestring

Resource type (always card)

data.transaction_idinteger

ID of the transaction

data.transaction_typestring

Type of the transaction

data.is_debitboolean

Whether it is a debit transaction

data.transaction_step_typestring

Step type of the transaction

data.decline_reasonstring

Code of the decline reason if applicable

data.transaction_statestring

The current state of the transaction

data.transaction_amount.valuedecimal

Transaction amount

data.transaction_amount.currencystring

Currency code

data.is_amount_confirmedboolean

Whether the transaction amount is confirmed

data.fees[0].amountdecimal

Fee amount

data.fees[0].currencystring

Currency code

data.fees[0].fee_typestring

Fee type

data.transaction_amount_with_fees.valuedecimal

Transaction amount including fees

data.transaction_amount_with_fees.currencystring

Currency code

data.billing_amount.valuedecimal

Billing amount

data.billing_amount.currencystring

Currency code

data.authorisation_methodstring

Authorisation method

data.balance_transaction_idinteger

Associated balance transaction id if applicable

data.debits[0].balance_idinteger

Balance ID

data.debits[0].debited_amount.valuedecimal

Amount taken from the balance

data.debits[0].debited_amount.currencystring

Currency code

data.debits[0].for_amount.valuedecimal

Amount converted to

data.debits[0].for_amount.currencystring

Currency code

data.debits[0].ratedecimal

Exchange rate

data.debits[0].fee.valuedecimal

Conversion fee amount

data.debits[0].fee.currencystring

Currency code

data.merchant.category.codestring

Merchant category code

data.merchant.category.descriptionstring

Merchant category description

data.arnstring

Acquirer reference number

data.creation_timedatetime

When transaction was created

data.occurred_atdatetime

When transaction or transaction state change occurred

Table of available transaction state and descriptions

CodeDescription
IN_PROGRESSThe transaction is still in progress
COMPLETEDThe transaction is completed
DECLINEDThe transaction has been declined
UNKNOWNDefault fallback status

Table of available transaction type and descriptions

CodeDescription
ACCOUNT_CREDITReceiving money on the card, excluding Visa OCT or Mastercard MoneySend
ACCOUNT_FUNDINGSending money to another card or e-wallet
CASH_ADVANCECash disbursement
CASH_WITHDRAWALATM withdrawal
CHARGEBACKCurrently unused. Reserved for future use.
CREDIT_TRANSACTIONVisa OCT and Mastercard MoneySend
ECOM_PURCHASEOnline purchase
POS_PURCHASEPurchase via a POS Terminal
REFUNDPartial or full refund of an existing card transaction

Table of available transaction step type and descriptions

CodeDescription
AUTHTransaction authorization which is usually the first step
PARTIAL_REVERSALTransaction has been partially reversed
FULL_REVERSALTransaction has been fully reversed
CAPTURETransaction has been caputured
SETTLECurrently unused. Reserved for future use.
REFUNDCurrently unused. Reserved for future use.
RECONCILIATIONCurrently unused. Reserved for future use.

Table of available fee type and descriptions

CodeDescription
ATM_WITHDRAWALFee charged by Wise
ATM_MACHINEFee charged by the ATM owner
Example `cards#transaction-state-change` event
{
"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"
}
}
],
"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.

You may receive update events even when there are no apparent changes in the dispute status or subStatus, as certain underlying modifications might not directly impact these visible indicators
Schema
data.resource.idstring

Unique ID of the dispute

data.resource.profile_idinteger

ID of the profile that owns the card

data.resource.transaction_idinteger

ID of the card transaction

data.resource.typestring

Resource type (always transaction-dispute)

data.reasonstring

Dispute reason, you can find all the possible values here

data.statusstring

Dispute overall status, it is either ACTIVE or CLOSED

data.sub_statusstring

Dispute detailed status, you can find all the possible values here

data.status_messagestring

Explanation for subStatus

data.created_atdatetime

Time when the dispute was created

data.created_bystring

Creator of the dispute, it is currently set to the user id

data.can_withdrawboolean

Whether the dispute can be withdrawn

data.occurred_atdatetime

When the dispute updates occurred

Example `transaction-disputes#update` event
{
"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"
}