Linked Account statuses
This page describes the general status transitions during Linked Account creation and verification.
Linked Account Statuses
Status transitions when you initiate a request to create a Linked Account that links to an external bank account, and subsequently verify it with micro-deposits.
| Status | Description |
|---|---|
| REQUIRES_ACTION | Indicates that customer action, such as verifying the Linked Account with microdeposits. |
| PROCESSING | Linked account activation is in progress, or the United Kingdom direct debit mandate is being registered. The customer should wait for the status to be updated. |
| SUCCEEDED | The request to create a Linked Account was successful. |
| FAILED | The request to create a Linked Account was unsuccessful. |
| SUSPENDED | Linked account has been suspended by Airwallex. |
You can subscribe to Linked Account webhook events to receive notifications in case of any status transitions.
Linked Account Failures
You can learn more about the causes of a Linked Account failure from the reason field and the failure_details object when the status of the Linked Account is FAILED or REQUIRES_ACTION, by either listening to the respective Linked Account webhook events or retrieving the Linked Account via Get Linked Account by ID API.
Use the table below to understand more about each failure reason:
| Linked account status | Reason | Description |
|---|---|---|
| REQUIRES_ACTION | MANDATE_FAILED | Mandate creation failed. |
| FAILED | VERIFICATION_FAILED | Unspecified errors default to VERIFICATION_FAILED. |
| FAILED | MICRO_DEPOSIT_FAILED | Micro-deposit verification failed. |
| FAILED | NAME_MATCH_FAILED | The name provided does not match the name on the Linked Account. |
If the failure came from the local clearing system, an additional failure_details object will also be returned to provide more information alongside the reason field, in the following structure:
code: Error code for this Linked Accountiso_code: Error code according to ISO 20022 standardsprovider_failure_details: If the error originated from the local clearing system, the response will contain this object with:local_clearing_system: name of the local clearing system that returned this error e.g. United States ACH (US_ACH)code: error code directly from the clearing systemmessage: error message directly from the clearing system
Please refer to the scheme-specific status transitions and clearing system error codes for each region under Direct debit scheme and mandate requirements.