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 typeProfile subscriptionsApplication subscriptions
transfers#state-changesupportedsupported
transfers#active-casessupportednot supported
balances#creditsupportednot supported
balances#updatesupportedsupported
balances#account-state-changenot supportedsupported
profiles#verification-state-changenot supportedsupported
batch-payment-initiations#state-changesupportedsupported
transfers#payout-failuresupportedsupported
transfers#refundsupportedsupported
swift-in#creditsupportednot supported
cards#transaction-state-changenot supportedsupported
profiles#cdd-check-state-changenot supportedsupported
cards#card-status-changenot supportedsupported
cards#card-order-status-changenot supportedsupported
partner-support#case-changednot supportedsupported
transaction-disputes#updatenot supportedsupported
bulk-settlement#payment-receivednot supportedsupported
users#state-changenot supportedsupported
  • 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.

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:

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

CodeDescription
ACCOUNT_CLOSEDThe recipient details are correct, but beneficiary account is closed
ACCOUNT_FROZENThe recipient details are correct, but beneficiary account is frozen
ACCOUNT_BLOCKEDThe recipient details are correct, but beneficiary account is blocked
ACCOUNT_LIMIT_REACHEDThe recipient details are correct, but beneficiary account has a limit that can be unblocked by the recipient
WRONG_ACCOUNT_NUMBERInvalid account number
WRONG_CARD_NUMBERInvalid card number
WRONG_ACCOUNT_DETAILSInvalid account number AND/OR invalid bank code
WRONG_ACCOUNT_TYPEIncorrect account type
WRONG_BANK_CODEInvalid sort/BIC/routing/etc number
WRONG_BRANCH_CODEInvalid branch code
WRONG_NAMEAccount number matches, but the name is not 100% correct
WRONG_PHONE_NUMBERRecipient phone number is incorrect
WRONG_ID_NUMBERInvalid recipient's ID document number
WRONG_RUT_NUMBERInvalid recipient's RUT (Rol Único Tributario) number
TAX_ID_NOT_MATCHINGTax ID doesn't match recipient's name
TAX_ID_SUSPENDEDTax ID is suspended
WRONG_REFERENCEInvalid payment reference
WRONG_PAYMENT_PURPOSEInvalid or not accepted payment purpose
ACCOUNT_DOES_NOT_EXISTFormat is correct but this account does not exist in recipient bank
WRONG_CURRENCYRecipient account is in different currency
WRONG_CARD_TYPERecipient account doesn't support payments to this card type
CANNOT_ACCEPT_FROM_3RD_PARTYRecipient bank can't accept the payments from 3rd party
CREDITING_ACCOUNT_FORBIDDENTerms and Conditions of Account do not permit crediting of these funds
DUPLICATE_ENTRYRecipient bank informs that there has been another payment in the same amount
FUNDS_NOT_EXPECTED_RETURNEDBeneficiary not expecting funds/instructed return
MANDATE_NOT_FILLED_INRecipient didn't fill out the mandate form on time or the email address is incorrect
BUSINESS_PAYMENTS_FORBIDDENPayment to business accounts are not allowed
DUPLICATE_ENTRYRecipient bank informs that there has been another payment in the same amount
SENDER_REQUESTED_TO_CANCELSender requested cancellation
REQUEST_FOR_INFORMATION_EXPIREDRequest for information expired
RETURN_REQUESTED_BY_RECIPIENTRecipient requested return
EXTERNAL_IDENTIFIER_DETAILS_HAVE_CHANGEDExternal identifier details have changed
REASON_NOT_SPECIFIEDReason 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"
}
  • Event type: transfers#refund
  • Profile level subscriptions: Supported
  • Application level subscriptions: Supported

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

This event provides information about refund amount and currency.

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

Schema
data.resource.typestring

Transfer resource type (always transfer)

data.resource.idinteger (long)

ID of the transfer

data.resource.profile_idinteger (long)

Identifies the Wise profile associated with this refund

data.resource.account_idinteger (long)

ID referring to the initial beneficiary of the payment. The ultimate beneficiary is the sender the funds are being refunded to.

data.resource.refund_amountdouble

The total amount that was refunded to the customer. Includes any applicable fees.

data.resource.refund_currencystring

The three-letter ISO currency code representing the currency in which the refund was issued.

data.occurred_atdatetime

The date and time the refund was triggered

Example `transfers#refund` event
{
"data": {
"resource": {
"type": "transfer",
"id": 111,
"profile_id": 222,
"account_id": 333,
"refund_amount": 5000,
"refund_currency": "EUR"
},
"occurred_at": "2024-01-01T12:34:56Z"
},
"subscription_id": "01234567-89ab-cdef-0123-456789abcdef",
"event_type": "transfers#refund",
"schema_version": "1.0.0",
"sent_at": "2024-01-01T12:34:56Z"
}

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"
}
  • 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.balance_idinteger
ID of the balance credited or debited
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,
"balance_id": 111,
"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.2.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,
"balance_id": 111,
"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.2.0",
"sent_at": "2023-03-08T15:26:07Z"
}
  • 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"
}
  • 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"
}
  • 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"
}
  • 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.

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.
Optional
Length: Min 1 Max 140 Characters

data.resource.recipient.addressstring

Address of the ultimate recipient.
Optional
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).
Optional
Length: Min 1 Max 36 Characters

data.resource.sender.namestring

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

data.resource.sender.addressstring

Address of the ultimate sender.
Optional
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).
Optional
Length: Min 1 Max 36 Characters

data.resource.sender.bank_code.valuestring

Value of the ultimate sender’s bank code.
Optional

data.resource.sender.bank_code.typestring

Type of the ultimate sender’s bank code.
Optional

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_amountobject

Amount originally instructed by the ultimate sender.
Optional

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

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

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"
}
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"
}
  • 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.credit.balance_idinteger

Balance ID

data.credit.credited_amount.valuedecimal

Amount credited to the balance

data.credit.credited_amount.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
CANCELLEDThe transaction has been cancelled
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"
}
}
],
"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: 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

CodeDescription
VERIFIEDAdditional verification check has passed
EVIDENCE_REQUIREDAdditional verification check has failed, evidences are required
CodeDescription
DOCUMENT_POOR_QUALITYDocument quality poor
DOCUMENT_OUT_OF_DATEDocument out of date
DOCUMENT_NAME_MISMATCHName on document does not match records
DOCUMENT_MISSING_NAMEName on document missing
DOCUMENT_MISSING_ISSUE_DATEDocument issue date missing
DOCUMENT_MISSING_COMPANY_LOGO_LETTERHEADCompany logo or letterhead missing from document
DOCUMENT_NOT_COMPLETEDocument is partially cut-off and does not contain full information
DOCUMENT_MISSING_SIGNATUREDocument missing signature
DOCUMENT_MISSING_INCOMEDocument missing income information or income is not clear from the document
DOCUMENT_TYPE_UNACCEPTABLESubmitted document type is not acceptable
INVOICE_UNACCEPTABLEInvoice is not an accepted document
PHOTO_ID_UNACCEPTABLEPhoto ID is not an accepted document
TRANSACTION_UNACCEPTABLETransaction (or a screenshot of a transaction) is not accepted
PHOTO_UNACCEPTABLEPhotos (or computer screenshots) are not acceptable
OTHERReason unknown

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"
}
  • 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#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: 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"
}
  • 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"
}
  • Event type: bulk-settlement#payment-received
  • Profile level subscriptions: Not Supported
  • Application level subscriptions: Supported

This event will be triggered when bulk settlement fund is received.

Schema
data.resource.settlement_referencestring

Reference on settlement journal

data.resource.source_currencystring

Settlement currency

data.resource.received_amountdecimal

The amount Wise received in this payment

data.resource.source_amountdecimal

The amount Wise paid out on behalf of partner

data.resource.target_amountdecimal

Total settlement fund received for this settlement journal

data.resource.amount_matchedboolean

Whether amount received matchs what is expected

data.occurred_atdatetime

When the settlement fund was received

Example `bulk-settlement#payment-received` event
{
"data": {
"resource": {
"settlement_reference": "TPFB1111111",
"source_currency": "GBP",
"received_amount": 10.1,
"source_amount": -100.1,
"target_amount": 100.1,
"amount_matched": true
},
"occurred_at": "2024-04-18T06:36:15Z"
},
"event_type": "bulk-settlement#payment-received",
"schema_version": "2.0.0",
"sent_at": "2024-04-18T06:36:17Z",
"subscription_id": "f5b51f77-e14a-433b-9f7c-fc2834ffcff5"
}
  • Event type: users#state-change
  • Profile level subscriptions: Not Supported
  • Application level subscriptions: Supported

This event will be triggered every time a user state is updated.

Schema
data.resource.idinteger

ID of the user

data.resource.typestring

Resource type (always user)

data.previous_statestring

The previous state of the user

data.current_statestring

The current state of the user

data.deactivation_type (optional)string

The type of deactivation, ACCOUNT_SUSPENSION or ACCOUNT_CLOSURE. If the type is ACCOUNT_SUSPENSION, it is possible for your customer support teams to appeal the deactivation by reaching out to Wise.

data.deactivation_reason (optional)string

The reason for deactivation

data.occurred_atdatetime

When the user state change occurred

Example `users#state-change` event
{
"data": {
"resource": {
"id": 1234,
"type": "user"
},
"previous_state": "ACTIVE",
"current_state": "WITHDRAW_ONLY",
"deactivation_type": "ACCOUNT_SUSPENSION",
"deactivation_reason": "REQUESTED_BY_CUSTOMER_CS",
"occurred_at": "2020-01-01T12:34:567Z"
},
"event_type": "users#state-change",
"schema_version": "2.0.0",
"sent_at": "2020-01-01T12:34:56Z",
"subscription_id": "f5b51f77-e14a-433b-9f7c-fc2834ffcff5"
}

The possible previous_state and current_state values are:

  • ACTIVE - The user's account is active.
  • WITHDRAW_ONLY - The user has 90 calendar days to remove their money from their balance before we fully close their account. This can be done through sending from their balance to themselves and others or spending with their card. The user will still be able to order new cards, convert between balances, open and close balances, and download balance statements. After 90 calendar days, the account will move into a DEACTIVATED state.
  • DEACTIVATED - The user's account is deactivated and they will not be able to perform any actions on their account. The end-user tokens will be revoked and you will receive a 401 Unauthorized response for API calls.
User state change transitions
User state change flow diagram