Event Types

The following event types are available. Please note that some event types are restricted to certain types of webhook subscription.

Event Types

Event type	Profile subscriptions	Application subscriptions
transfers#state-change	supported	supported
transfers#active-cases	supported	not supported
balances#credit	supported	not supported
balances#update	supported	supported
balances#account-state-change	not supported	supported
profiles#verification-state-change	not supported	supported
batch-payment-initiations#state-change	supported	supported
transfers#payout-failure	supported	supported
swift-in#credit	supported	not supported
cards#transaction-state-change	not supported	supported
profiles#cdd-check-state-change	not supported	supported
cards#card-status-change	not supported	supported
cards#card-order-status-change	not supported	supported
partner-support#case-changed	not supported	supported

Transfer state change event

Event type: transfers#state-change
Profile level subscriptions: Supported
Application level subscriptions: Supported

This event will be triggered every time a transfer's status is updated. Each event contains a timestamp. As we do not guarantee the order of events, please use data.occurred_at to reconcile the order.

If you would like to subscribe to transfer state change events, please use transfers#state-change when creating your subscription.

Note that for all topup-to-balance transfers created, transfers#state-change events will NOT be triggered. To listen to these, subscribe to balances#update webhook.

Schema

data.resource.typestring

Transfer resource type (always transfer)

data.resource.idinteger (long)

ID of the transfer

data.resource.profile_idinteger (long)

ID of the profile that owns the transfer

data.resource.account_idinteger (long)

ID of transfer's recipient account

data.current_statestring

Current transfer state (see transfer statuses)

data.previous_statestring or null

Previous transfer state (see transfer statuses) - Note that this will be null for newly created transfers.

data.occurred_atdatetime

When the state change occurred.

Transfer Statuses

You should use a subscription to application webhooks to keep the statuses of your local transfer data storage up to date. The transfers will move through the following statuses in the happy path.

Incoming Payment Waiting ⇒ Processing ⇒ Funds Converted ⇒ Outgoing Payment Sent

Outgoing Payment Sent is the final state of the normal flow. If the payment fails, the following problematic flow will occur. An example would be if the recipient bank account doesn’t exist or the data is entered incorrectly and the payment is returned to Wise. The problematic state flow of transfers is:

Outgoing Payment Sent ⇒ Bounced Back ⇒ Processing ⇒ Cancelled ⇒ Funds Refunded

Most bounce backs occur within 2-3 business days, however this could happen up to several weeks after a transfer is sent.

Transfer state flow

alt text

NB: Transfers support rollback transitions. This allows transfers to return back to previous states.

See below for the full list of transfer statuses and what they mean in the order of occurrence.

incoming_payment_waiting – The transfer has been submitted and Wise is waiting for funding to be initiated.
incoming_payment_initiated - The funding has been initiated but the money has not yet arrived in Wise's account.
processing – We have received the funds and are processing the transfer. Processing is a generic term that means we’re doing behind-the-scene activities before the money gets sent to the recipient, such as AML, compliance and fraud checks.
funds_converted – All compliance checks have been completed for the transfer and funds have been converted from the source currency to the target currency.
outgoing_payment_sent – Wise has paid out funds to the recipient. This is the final state of the transfer, assuming funds will not be returned. When a transfer has this state, it doesn’t mean the money has arrived in the recipient’s bank account, just that we have sent it from ours. Note: Payment systems in different countries operate in different speeds and frequency. For example, in the UK, the payment will reach the recipient bank account within few minutes after we send the outgoing payment. However, in the US it usually takes a day until funds are received.
cancelled – This status is used when the transfer was never funded and therefore never processed. This is a final state of the transfer.
funds_refunded – Transfer has been refunded. This is a final state of the transfer.
bounced_back – Transfer has bounced back but has not been cancelled nor refunded yet. This is not a final transfer state, it means the transfer will either be delivered after a delay or it will turn to funds_refunded state.
charged_back - This status is used when we have a problem debiting payer's account or the payer requested money back. Chargeback can happen from any other state.
unknown - This status is used when we don’t have enough information to move the transfer into a final state. We send out an email for more information. For example sender account details to refund money back.

Keep in mind the transfer statuses in our API have different names than what you’ll see on our website or app. That’s because we use more consumer friendly language in the front end of our products. For example "Completed" on our website means outgoing_payment_sent in the API.

You should use the following descriptions in your website or app for the potential statuses we return:

Status	Description
incoming_payment_waiting	"On its way to Wise"
incoming_payment_initiated	"On its way to Wise"
processing	"Processing"
funds_converted	"Processing"
outgoing_payment_sent	"Sent"
charged_back	"Charged back"
cancelled	"Cancelled"
funds_refunded	"Refunded"
bounced_back	"Bounced back"
unknown	"Unknown"

Example `transfers#state-change` event

{
  "data": {
    "resource": {
      "type": "transfer",
      "id": 111,
      "profile_id": 222,
      "account_id": 333
    },
    "current_state": "processing",
    "previous_state": "incoming_payment_waiting",
    "occurred_at": "2020-01-01T12:34:56Z"
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "transfers#state-change",
  "schema_version": "2.0.0",
  "sent_at": "2020-01-01T12:34:56Z"
}

Full reference

Transfer active cases event

Event type: transfers#active-cases
Profile level subscriptions: Supported
Application level subscriptions: Not Supported

This event will be triggered every time a transfer's list of active cases is updated. Active cases indicate potential problems with transfer processing.

If you would like to subscribe to transfer active cases events, please use transfers#active-cases when creating your subscription.

Schema

data.resource.typestring

Transfer resource type (always transfer)

data.resource.idinteger

ID of the transfer

data.resource.profile_idinteger

ID of the profile that owns the transfer

data.resource.account_idinteger

ID of transfer's recipient account

data.active_caseslist of strings

Ongoing issues related to the transfer

Example `transfers#active-cases` event

{
  "data": {
    "resource": {
      "type": "transfer",
      "id": 111,
      "profile_id": 222,
      "account_id": 333
    },
    "active_cases": ["deposit_amount_less_invoice"]
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "transfers#active-cases",
  "schema_version": "2.0.0",
  "sent_at": "2020-01-01T12:34:56Z"
}

Transfer payout failure events

Event type: transfers#payout-failure
Profile level subscriptions: Supported
Application level subscriptions: Supported

This event will be triggered every time a payout fails. The event can be used to get further information about a failed payment.

transfers#state-change event provides high level information about the state of transfers. But it doesn't provide details about payout failures.

While the transfers#state-change event is in outgoing_payment_sent state, the payout could fail for certain reasons listed below.

Using this event, you can understand the reason behind the failure and even ask your customers to fix the problem by themselves. If the failure reason code is WRONG_ACCOUNT_NUMBER for example.

Please note that not every payout failure will trigger a transfers#state-change. For example a payout might fail with MANDATE_NOT_FILLED_IN code but the corresponding transfer might stay in the same state.

We recommend to process both event types(transfers#payout-failure and transfers#state-change) separate from each other.

If you would like to subscribe to payout failure events, please use transfers#payout-failure when creating your subscription.

Schema

data.transfer_idinteger

ID of the transfer

data.profile_idinteger

ID of the profile that initiated the transfer

data.failure_reason_codestring

Code of the failure error

data.failure_descriptionstring

Description of the failure code

data.occurred_atdatetime

When the state change occurred

Table of available failure reason codes and descriptions

Code	Description
ACCOUNT_CLOSED	The recipient details are correct, but beneficiary account is closed
ACCOUNT_FROZEN	The recipient details are correct, but beneficiary account is frozen
ACCOUNT_BLOCKED	The recipient details are correct, but beneficiary account is blocked
ACCOUNT_LIMIT_REACHED	The recipient details are correct, but beneficiary account has a limit that can be unblocked by the recipient
WRONG_ACCOUNT_NUMBER	Invalid account number
WRONG_CARD_NUMBER	Invalid card number
WRONG_ACCOUNT_DETAILS	Invalid account number AND/OR invalid bank code
WRONG_ACCOUNT_TYPE	Incorrect account type
WRONG_BANK_CODE	Invalid sort/BIC/routing/etc number
WRONG_BRANCH_CODE	Invalid branch code
WRONG_NAME	Account number matches, but the name is not 100% correct
WRONG_PHONE_NUMBER	Recipient phone number is incorrect
WRONG_ID_NUMBER	Invalid recipient's ID document number
WRONG_RUT_NUMBER	Invalid recipient's RUT (Rol Único Tributario) number
TAX_ID_NOT_MATCHING	Tax ID doesn't match recipient's name
TAX_ID_SUSPENDED	Tax ID is suspended
WRONG_REFERENCE	Invalid payment reference
WRONG_PAYMENT_PURPOSE	Invalid or not accepted payment purpose
ACCOUNT_DOES_NOT_EXIST	Format is correct but this account does not exist in recipient bank
WRONG_CURRENCY	Recipient account is in different currency
WRONG_CARD_TYPE	Recipient account doesn't support payments to this card type
CANNOT_ACCEPT_FROM_3RD_PARTY	Recipient bank can't accept the payments from 3rd party
CREDITING_ACCOUNT_FORBIDDEN	Terms and Conditions of Account do not permit crediting of these funds
DUPLICATE_ENTRY	Recipient bank informs that there has been another payment in the same amount
FUNDS_NOT_EXPECTED_RETURNED	Beneficiary not expecting funds/instructed return
MANDATE_NOT_FILLED_IN	Recipient didn't fill out the mandate form on time or the email address is incorrect
BUSINESS_PAYMENTS_FORBIDDEN	Payment to business accounts are not allowed
DUPLICATE_ENTRY	Recipient bank informs that there has been another payment in the same amount
REASON_NOT_SPECIFIED	Reason not specified

Wise could add new failure codes to this list and your system should be able to handle the events even if the failure reason code is not recognised.

Example `transfers#payout-failure` event

{
  "data": {
    "transfer_id": 111,
    "profile_id": 222,
    "failure_reason_code": "WRONG_ID_NUMBER",
    "failure_description": "Invalid recipient's ID document number",
    "occurred_at": "2023-08-10T10:17:23.000+00:00"
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "transfers#payout-failure",
  "schema_version": "2.0.0",
  "sent_at": "2023-08-10T10:17:28Z"
}

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

Balance account state change event

Event type: balances#account-state-change
Profile level subscriptions: Not Supported
Application level subscriptions: Supported

This event will be triggered every time a balance account is activated or deactivated

If you would like to subscribe to balance account state change events, please use balances#account-state-change 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.resource.stateinteger

State of the account.
Values:

ACTIVE
INACTIVE

data.occurred_atdatetime

Timestamp when the event occurred

Example `balances#account-state-change` event

{
  "data":{
    "resource":{
      "type":"balance-account",
      "id": 123,
      "profile_id": 555,
      "state": "INACTIVE"
    },
    "occurred_at":"2020-01-01T12:34:56Z"
  },
  "subscription_id":"01234567-89ab-cdef-0123-456789abcdef",
  "event_type":"balances#account-state-changed",
  "schema_version":"2.0.0",
  "sent_at":"2020-01-01T12:34:56Z"
}

Verification state change event

Event type: profiles#verification-state-change
Profile level subscriptions: Not Supported
Application level subscriptions: Supported

This event will be triggered when the verification state of a connected profile changes.

A profile's verification state can be verified or not_verified. If the state is verified, then the user is ready to make payments using Wise. If the state is not_verified, then we advise not to initiate any transfers with the user's access token as the payments will not be processed until the verification is completed.

If you would like to subscribe to verification state change events, please use profiles#verification-state-change when creating your subscription.

Schema

data.resource.typestring

Profile resource type (always profile)

data.resource.idinteger

ID of the profile

data.current_statestring

Current verification state of the profile (see discussion above)

data.occurred_atdatetime

When the verification state change occurred

Example `profiles#verification-state-change` event

{
  "data": {
    "resource": {
      "type": "profile",
      "id": 111
    },
    "current_state": "verified",
    "occurred_at": "2020-01-01T12:34:56Z"
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "profiles#verification-state-change",
  "schema_version": "2.0.0",
  "sent_at": "2020-01-01T12:34:56Z"
}

Batch Payment Initiations state change event

Event type: batch-payment-initiations#state-change
Profile level subscriptions: Supported
Application level subscriptions: Supported

This event will be triggered when the payment initiation state of a batch group payment changes.

The expected state of a batch payment initiation can be one of: NEW, PROCESSING, COMPLETED, FAILED, CHARGED_BACK.

If you would like to subscribe to batch payment initiation state change events, please use batch-payment-initiations#state-change when creating your subscription.

Schema

data.resource.idnumber

Payment initiation ID

data.resource.batchGroupIdtext

Batch group ID

data.resource.profileIdnumber

The ID of the profile this payment belongs to

data.previousStatustext

Previous payment initiation state

data.currentStatustext

Current payment initiation state

data.occurredAttimestamp

When the payment initiation state change occurred

data.returnCodetext

Return code of the underlying payment system

Example `batch-payment-initiations#state-change` event

{
  "data": {
    "resource": {
      "id": 12345,
      "batchGroupId": "068e186d-9632-4937-b753-af3e53f4d0b0",
      "profileId": 2
    },
    "previousStatus": "NEW",
    "newStatus": "PROCESSING",
    "occurredAt": "2021-04-13T19:51:41.423404Z" ,
    "returnCode": "200"
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "batch-payment-initiations#state-change",
  "schema_version": "2.0.0",
  "sent_at": "2020-01-01T12:34:56Z"
}

SWIFT receive credit events

Triggering event type: swift-in#credit
Profile level subscriptions: Supported
Application level subscriptions: Not Supported

This webhook will be sent every time a SWIFT message is received and a credit is deposited into a balance account.
Please note: It is recommended that you do not subscribe to balances#credit or transfers#state-change on the same profile to avoid duplication of webhook details.

Version 3.0.0 (latest)

Schema

data.action.typestring

Type of action.
Mandatory
Format: always credit

data.action.idinteger

TransferID of the credit.
Mandatory

data.action.profile_idinteger

ProfileID for the transfer.
Mandatory

data.action.account_idinteger

AccountID for the transfer.
Mandatory

data.resource.idinteger

ID of the webhook.
Mandatory

data.resource.uetrguid

Unique identifier created by the scheme for each payment and passed through the scheme to Wise.
Mandatory
Length: 36 Characters

data.resource.referencestring

Reference provided by the ultimate sender for the payment.
Optional
Length: Min 0 Max 140 Characters

data.resource.recipient.namestring

Name of the ultimate recipient.
Mandatory
Length: Min 1 Max 140 Characters

data.resource.recipient.addressstring

Address of the ultimate recipient.
Mandatory
Length: Min 1 Max 140 Characters

data.resource.recipient.accountstring

This can be either an IBAN, BBAN, AccountId or a Descriptor (another kind of identifier).
Mandatory
Length: Min 1 Max 36 Characters

data.resource.sender.namestring

Name of the ultimate sender.
Mandatory
Length: Min 1 Max 140 Characters

data.resource.sender.addressstring

Address of the ultimate sender.
Mandatory
Length: Min 1 Max 140 Characters

data.resource.sender.accountstring

This can be either an IBAN, BBAN, AccountId or a Descriptor (another kind of identifier).
Mandatory
Length: Min 1 Max 36 Characters

data.resource.sender.bank_code.valuestring

Value of the ultimate sender’s bank code.
Mandatory

data.resource.sender.bank_code.typestring

Type of the ultimate sender’s bank code.
Mandatory

data.resource.exchange_ratedouble

In case the originally instructed amount was converted by Wise or any other intermediary agent, this field contains the exchange rate used. If no conversion took place, the exchange rate will be 1.0.
Mandatory

data.resource.instructed_amount.valuedouble

Value of the amount originally instructed by the ultimate sender.
Mandatory

data.resource.instructed_amount.currencystring

Currency of the amount originally instructed by the ultimate sender.
Mandatory
Length: Exactly 3 Characters
Format: 3-letter ISO currency code

data.resource.settled_amount.valuedouble

Value of the amount settled to the balance account.
Mandatory

data.resource.settled_amount.currencystring

Currency of the amount settled to the balance account.
Mandatory
Length: Exactly 3 Characters
Format: 3-letter ISO currency code

data.resource.fee.wise[]list

List of fees applied by Wise (e.g., conversion fee). If this list is empty, no fees were applied by Wise.
Mandatory

data.resource.fee.wise[].typestring

Type of fee.
Mandatory
Format: conversion,

data.resource.fee.wise[].valuedouble

Value of fee.
Mandatory

data.resource.fee.wise[].currencystring

Currency of fee.
Mandatory
Length: Exactly 3 Characters
Format: 3-letter ISO currency code

data.resource.fee.correspondent[]list

List of fees declared by correspondents (e.g., handling fee). If this list is empty, no fees were declared by correspondents.
Mandatory

data.resource.fee.correspondent[].valuedouble

Value of fee.
Mandatory

data.resource.fee.correspondent[].currencystring

Currency of fee.
Mandatory
Length: Exactly 3 Characters
Format: 3-letter ISO currency code

data.resource.transaction_timedatetime

Date and time at which the associated transaction was created. Time in UTC.
Mandatory
Length: Exactly 20 Characters
Format: YYYY-MM-DDTHH:MM:SSZ

data.occurred_atdatetime

Date and time at which the amount was credited to the balance account. Time in UTC.
Mandatory
Length: Exactly 20 Characters
Format: YYYY-MM-DDTHH:MM:SSZ

Example `swift-in#credit` event (JSON format)

{
  "data": {
    "action": {
      "type": "credit",
      "id": 12345,
      "profile_id": 222,
      "account_id": 333
    },
    "resource": {
      "id": "55555",
      "uetr": "f875814b-7d44-4d1b-a499-123456789abcde",
      "reference": "/RFB/BET072",
      "recipient": {
        "name": "JOHN SMITH",
        "address": "EVERGREEN AVE, 6, BRUSSELS, BE",
        "account": "BE1234567891234"
      },
      "sender": {
        "name": "GEORGE SMITH",
        "address": "EVERGREEN STREET, 10, BRUSSELS, BE",
        "account": "EE947700771111111111",
        "bank_code": {
          "value": "ABNABE2AIDJ",
          "type": "BIC"
        }
      },
      "exchange_rate": 0.8,
      "instructed_amount": {
        "value": 1000,
        "currency": "USD"
      },
      "settled_amount": {
        "value": 786.54,
        "currency": "GBP"
      },
      "fee": {
        "wise": [
          {
              "type": "conversion",
              "value": 2.76,
              "currency": "GBP"
          }
        ],
        "correspondent": [
          {
            "value": 4.5,
            "currency": "USD"
          },
          {
            "value": 2.1,
            "currency": "GBP"
          },
          {
            "value": 5,
            "currency": "GBP"
          }
        ]
      },
      "transaction_time": "2023-08-21T12:34:56Z"
    },
    "occurred_at": "2023-08-21T12:34:56Z"
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "swift-in#credit",
  "schema_version": "3.0.0",
  "sent_at": "2023-08-21T12:34:58Z"
}

Version 2.0.0

Schema

data.action.typestring

Type of action (always CREDIT)

data.action.idinteger

TransferID of the credit

data.action.profile_idinteger

ProfileID for the transfer

data.action.account_idinteger

AccountID for the transfer

data.resource.typestring

SWIFT message type

data.resource.idinteger

ID of webhook

data.resource.messagestring

Complete SWIFT Message as received

data.occurred_atdatetime

When the credit occurred

Example `swift-in#credit` event

{
    "data": {
        "action": {
              "type": "CREDIT",
              "id": 12345,
              "profile_id": 222,
              "account_id": 333
        },
        "resource": {
            "id": "55555",
            "type": "103",
            "message": "
                {1:F21TRWIGB22AXXX123456789}{4:{177:0123456789}{451:0}}{1:F01TRWIGB22AXXX12345678}{2:O1030727211112LHVBEE22AXXX15007123456789912345WN}{3:{108:ASW86540/12112FA}{119:STP}{111:001}{121:f875814b-7d44-4d1b-a499-123456789abcde}}{4:
                :20:ASW86540/123456
                :23B:CRED
                :26T:K90
                :32A:211112EUR3,54
                :33B:EUR3,54
                :50F:/EE947700771111111111
                1/SMITH#JOHN
                2/EVERGREEN STREET, 10
                3/BE/BRUSSELS
                4/12345678
                :52A:ZYABEE20
                :57A:AGRNMD2XXXX
                :59F:/BE1234567891234
                1/SMITH#JOHN
                2/EVERGREEN AVE, 6
                3/BE/BRUSSELS
                :70:/RFB/BET072
                :70:/INV/abc/SDF-96//1234-234///ROC/98I
                U87
                :70:/TSU/00000089963-0820-01/ABC-15/256
                214,
                :71A:SHA
                -}
            "
        }
        "occurred_at": "2020-01-01T12:34:56Z"
    },
    "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
    "event_type": "swift-in#credit",
    "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"
}

Additional verification state change event

Event type: profiles#cdd-check-state-change
Profile level subscriptions: Not Supported
Application level subscriptions: Supported

This event pushes updates for Additional Customer Verification process.

Schema

data.resource.typestring

Profile resource type (always set to profile)

data.resource.idinteger

ID of the profile

data.current_statestring

Current verification state of the profile (see table below)

data.review_outcomestring

Optional

Reason the verification review did not pass.

Refer to the table below for description on these reasons.

data.required_evidenceslist of strings

List of required evidences for verification.

Refer to the table below for description on how to provide the missing evidence.

data.occurred_atdatetime

When the CDD check state change occurred

data.source_of_incomestring

Optional

Source of income for a personal profile submitted via the /upload-evidences API.

Use this to upload the correct Source of Wealth document.

data.source_of_fundingstring

Optional

Source of funding for a business profile submitted via the /upload-evidences API.

Use this to upload the correct Source of Wealth document.

Verification state values

Code	Description
VERIFIED	Additional verification check has passed
EVIDENCE_REQUIRED	Additional verification check has failed, evidences are required

Review outcome values

Code	Description
DOCUMENT_POOR_QUALITY	Document quality poor
DOCUMENT_OUT_OF_DATE	Document out of date
DOCUMENT_NAME_MISMATCH	Name on document does not match records
DOCUMENT_MISSING_NAME	Name on document missing
DOCUMENT_MISSING_ISSUE_DATE	Document issue date missing
DOCUMENT_MISSING_COMPANY_LOGO_LETTERHEAD	Company logo or letterhead missing from document
DOCUMENT_NOT_COMPLETE	Document is partially cut-off and does not contain full information
DOCUMENT_MISSING_SIGNATURE	Document missing signature
DOCUMENT_MISSING_INCOME	Document missing income information or income is not clear from the document
DOCUMENT_TYPE_UNACCEPTABLE	Submitted document type is not acceptable
INVOICE_UNACCEPTABLE	Invoice is not an accepted document
PHOTO_ID_UNACCEPTABLE	Photo ID is not an accepted document
TRANSACTION_UNACCEPTABLE	Transaction (or a screenshot of a transaction) is not accepted
PHOTO_UNACCEPTABLE	Photos (or computer screenshots) are not acceptable
OTHER	Reason unknown

Required evidence values

Go to the list of evidences to find all possible values.

Example `profiles#cdd-check-state-change` event

{
  "data": {
    "resource": {
      "type": "profile",
      "id": 111
    },
    "current_state": "VERIFIED",
    "required_evidences": [],
    "occurred_at": "2020-01-01T12:34:56Z"
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "profiles#cdd-check-state-change",
  "schema_version": "2.0.0",
  "sent_at": "2020-01-01T12:34:56Z"
}

Another example `profiles#cdd-check-state-change` event

{
  "data": {
    "resource": {
      "type": "profile",
      "id": 111
    },
    "current_state": "EVIDENCE_REQUIRED",
    "review_outcome": "Document is not acceptable",
    "required_evidences": [
      "SOURCE_OF_INCOME"
    ],
    "source_of_income": "INVESTMENTS",
    "occurred_at": "2020-01-01T12:34:56Z"
  },
  "subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
  "event_type": "profiles#cdd-check-state-change",
  "schema_version": "2.0.0",
  "sent_at": "2020-01-01T12:34:56Z"
}

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

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",
  },
  "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 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.orderIdstring

Card order id associated with the status change

data.orderStatusstring

Updated card order status

data.deliveryVendorstring or null

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

data.deliveryVendorUrlstring or null

Url to get vendor tracking details (physical card only)

data.occurredAtdatetime

When the state 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",
      "delivery_vendor_url": "www.dhl.com/tracking",
      "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

Partner Support Case Changed

Event type: partner-support#case-changed
Profile level subscriptions: Not supported
Application level subscriptions: Supported

This event will be triggered every time a partner case is updated, including if commented on or if the status is changed.

Note that you will also receive a webhook response when you have created a new case or updated a case.

As this the Partner Support API is currently in beta, the information below may change. We will be adding in new types of cases, so please ensure that you handle additional undocumented types.

Schema

data.resource.typestring

Type of the partner case. Value must be GENERAL_ENQUIRY. More case types will be added in the future.

data.resource.case_idlong

ID of the partner case

data.resource.details.transfer_idlong

ID of the transfer that is associated with the partner case. This can be null.

data.resource.details.profile_idinteger (long)

ID of the profile that is associated with the partner case.

data.resource.details.user_idinteger (long)

ID of the user account that is associated with the partner case.

statusstring

Status of the case. Can include OPEN, PENDING, SOLVED and CLOSED.

data.resource.typestring

Type of resource for webhook. Will always be partner-support-case

data.typestring

The type of the webhook being sent. Will be STATUS_UPDATED , NEW_COMMENT , or NEW_CASE

data.occurred_atdatetime

When the partner case update occurred.

Example `partner-support#case-changed` event

{
  "data": {
    "resource": {
      "case_id": 136,
      "case_type": "GENERAL_ENQUIRY",
      "details": {
        "transfer_id": 12345678,
        "user_id": 12345678,
        "profile_id": 12345678
      },
      "status": "PENDING",
      "type": "partner-support-case"
    },
    "type": "NEW_CASE",
    "occurred_at": "2023-06-23T09:45:34Z"
  },
  "subscription_id": "017631af-326c-4a69-93f3-bd1ce987a743",
  "event_type": "partner-support#case-changed",
  "schema_version": "2.0.0",
  "sent_at": "2023-06-23T09:45:36Z"
}