Webhooks

Webhooks are also provided to give you notifications on customer activities.

The Webhook Resource

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"
}

Card order status change events

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:

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)

Card order status transitions

Create card order statuses transition diagram

Card status change events

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

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)

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"
}

Card transaction state change events

Event type: cards#transaction-state-change
Profile level subscriptions: Not Supported
Application level subscriptions: Supported

This event will be triggered every time a new card transaction is made or the transaction state changes.

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

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
UNKNOWN	Default fallback status

Table of available fee type and descriptions

Code	Description
ATM_WITHDRAWAL	Fee charged by Wise
ATM_MACHINE	Fee 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",
    "decline_reason": null,
    "transaction_state": "IN_PROGRESS",
    "transaction_amount": {
      "value": 100.00,
      "currency": "EUR"
    },
    "fees": [
      {
        "amount": 1.00,
        "currency": "EUR",
        "fee_type": "ATM_WITHDRAWAL"
      }
    ],
    "transaction_amount_with_fees": {
      "value": 101.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"
        }
      }
    ],
    "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"
}

Transaction disputes update events

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"
}