Verify a beneficiary account

Airwallex offers real-time bank account verification to enable customers to transfer funds with confidence. By verifying bank account details before transfers are created, Airwallex can help to reduce failures, mitigate fraud and prevent misdirected funds being sent.

Airwallex is continuously expanding its geographical and clearing system coverage to verify bank accounts. See Supported transfer methods for details. By navigating to the subpages on the left menu, you can find region-specific guides with detailed request field requirements, applicable verification results, and other key considerations.

Call Verify a beneficiary account API to confirm if a beneficiary bank account is valid and, where supported, check if the specified account name matches the registered bank account details.

Step 1: Prepare required beneficiary information

This API accepts beneficiary bank account details in the same structure as the Create a new beneficiary API. Before calling the API, please collect the required account details in the correct format, which can vary depending on the region and transfer method. See more details in Create a transfer to learn more about preparing beneficiary account details.

We also recommend to Validate a beneficiary first and resolve any errors before calling this API for advanced verifications.

Step 2: Verify a beneficiary account

Include the following request parameters to provide beneficiary account details:

account_details: The beneficiary account details to be verified. Refer to the region-specific guides for required fields within this object.
transfer_method: Currently, only LOCAL is supported. Note that for API versions prior to 2024-09-27, specify the payment_method parameter instead.
entity_type: Specify whether the beneficiary is an individual (PERSONAL) or a business (COMPANY).

The API responds with the following fields:

code: The high-level outcome of account verification.
- VERIFIED: The account provided is valid, regardless of whether the account name matches. When available, the name match result will be disclosed in the details object.
- INVALID: The account does not exist or has been closed.
- CANNOT_VERIFY: This account cannot be verified.
- EXTERNAL_SERVICE_UNAVAILABLE: The downstream service is temporarily unavailable.
message: Description of the code.
details: An object containing additional verification details (if available).
- account_name_match_result: Name match result for the account_name provided under account_details. Could be one of FULL_MATCH, PARTIAL_MATCH, NOT_MATCHED, FULL_MATCH_INCORRECT_TYPE, or PARTIAL_MATCH_INCORRECT_TYPE. See detailed handling instructions in Step 3.
- resolved_account_name: Name of the account holder.
- resolved_bank_name: Name of the account-holding financial institution.

Example request

Shell

If you are registered as a platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the x-on-behalf-of header.

Example response

JSON

Errors

Airwallex uses conventional HTTP response codes API to indicate the success or failure of an API request.

A HTTP 400 status code indicates an error triggered due to the information provided in the request, including but not limited to incorrect request structures and invalid field formats for this API. See Error codes to learn about the possible errors associated with invalid beneficiary details.

Step 3: Handle verification results

Use the code and account_name_match_result fields in the response to determine next steps in your workflow. Please refer to the full list of verification results below, as well as the region-specific guides (e.g., United Kingdom).

Code	Account name match result	Scenario	Recommended handling
`VERIFIED`	`FULL_MATCH`	This is a valid account, and the account name matches the bank record.	Proceed with creating the beneficiary or transfer.
`VERIFIED`	`PARTIAL_MATCH`	This is a valid account, and the account name is a partial match with the bank record.	Confirm details with your beneficiary before proceeding. Update the account name if confirmed.
`VERIFIED`	`NOT_MATCHED`	This is a valid account, but the account name doesn’t match the bank record.	Confirm details with your beneficiary before proceeding. Update the account name if confirmed.
`VERIFIED`	`FULL_MATCH_INCORRECT_TYPE`	This is a valid account and the account name matches, but the `entity_type` provided is wrong.	Confirm details with your beneficiary before proceeding. Update the entity type if confirmed.
`VERIFIED`	`PARTIAL_MATCH_INCORRECT_TYPE`	This is a valid account and the account name is a partial match, but the entity_type provided is wrong.	Confirm details with your beneficiary before proceeding. Update the account name and entity type if confirmed.
`INVALID`	-	The account does not exist or has been closed.	Do NOT proceed. We do not support transferring to this account.
`CANNOT_VERIFY`	-	This account cannot be verified because the bank/branch/account is outside the verification coverage, or the account holder has opted out.	Proceed with caution after confirming your beneficiary details.
`EXTERNAL_SERVICE_UNAVAILABLE`	-	The downstream service is unavailable at the moment.	Retry later; or proceed after confirming beneficiary details.

Please note that for any result other than FULL_MATCH, there is a risk of misdirected transfers. Transfers cannot be created for INVALID accounts, but for all other scenarios you can still proceed at your own discretion. We strongly recommend that you double-check all details with your intended beneficiary, as funds sent to the wrong account might not be recoverable.

Supported transfer methods

Region	Transfer method	Payment scheme	Verification source	Name matching supported
Europe (SEPA countries)	LOCAL	SEPA Instant / SEPA	Verification of Payee (VoP)	Yes
United Kingdom	LOCAL	Faster Payments, CHAPS	Confirmation of Payee (CoP)	Yes
Viet Nam	LOCAL		NAPAS	Yes
Australia (Upcoming)	LOCAL	NPP, BANK_TRANSFER	Confirmation of Payee (CoP)	No

Was this page helpful?