Webhooks

We also provide webhooks that help to give you real-time notifications on customer spend, providing you with even more tools at your disposal to create seamless flows for your users.

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

Balance credit event

New balance webhook is released The new webhook is triggered every time a multi-currency account is credited or debited . For more information: Balance update event

Event type: balances#credit
Profile level subscriptions: Supported
Application level subscriptions: Not Supported

This event will be triggered every time a multi-currency account is credited.

If you would like to subscribe to balance credit events, please use balances#credit when creating your subscription.

Schema

data.resource.typestring

Resource type (always balance-account)

data.resource.idinteger

ID of the account

data.resource.profile_idinteger

ID of the profile that owns the account

data.transaction_typestring

Always credit

data.amountdecimal

Deposited amount

data.currencystring

Currency code

data.post_transaction_balance_amountdecimal

Balance after the credit was applied

data.occurred_atdatetime

When the credit occurred

Example `balances#credit` event

{
   "data":{
      "resource":{
         "type":"balance-account",
         "id":111,
         "profile_id":222
      },
      "transaction_type":"credit",
      "amount":1.23,
      "currency":"EUR",
      "post_transaction_balance_amount":2.34,
      "occurred_at":"2020-01-01T12:34:56Z"
   },
   "subscription_id":"01234567-89ab-cdef-0123-456789abcdef",
   "event_type":"balances#credit",
   "schema_version":"2.0.0",
   "sent_at":"2020-01-01T12:34:56Z"
}

Balance update event

Event type: balances#update
Profile level subscriptions: Supported
Application level subscriptions: Supported

This event will be triggered every time a multi-currency account is credited or debited.

If you would like to subscribe to balance update events, please use balances#update when creating your subscription.

Schema

data.resource.typestring

Resource type (always balance-account)

data.resource.idinteger

ID of the account

data.resource.profile_idinteger

ID of the profile that owns the account

data.transaction_typestring

Either credit or debit

data.amountdecimal

Transaction amount

data.currencystring

Currency code

data.occurred_atdatetime

When the transaction occurred

data.transfer_referencestring

ID of the transfer

data.channel_namestring

transfer category

Example `balances#update` event, credit notification

{
  "data": {
    "resource": {
      "id": 2,
      "profile_id": 2,
      "type": "balance-account"
    },
    "amount": 70,
    "currency": "GBP",
    "transaction_type": "credit",
    "occurred_at": "2023-03-08T14:55:38Z",
    "transfer_reference": "BNK-1234567",
    "channel_name": "TRANSFER"
  },
  "subscription_id": "f2264fe5-a0f5-4dab-a1b4-6faa87761425",
  "event_type": "balances#update",
  "schema_version": "2.1.0",
  "sent_at": "2023-03-08T14:55:39Z"
}

Example `balances#update event`, debit notification

{
  "data": {
    "resource": {
      "id": 2,
      "profile_id": 2,
      "type": "balance-account"
    },
    "amount": 9.6,
    "currency": "GBP",
    "transaction_type": "debit",
    "occurred_at": "2023-03-08T15:26:07Z",
    "transfer_reference": "47500002",
    "channel_name": "TRANSFER"
  },
  "subscription_id": "f2264fe5-a0f5-4dab-a1b4-6faa87761425",
  "event_type": "balances#update",
  "schema_version": "2.1.0",
  "sent_at": "2023-03-08T15:26:07Z"
}