Verify a beneficiary account

Call Verify a beneficiary account API to confirm if a beneficiary account is valid and, where supported, check if the provided account name matches the registered account details. This API can be used to reduce failures, mitigate fraud, and prevent misdirected funds before transfers are created.

This capability is rolling out by region. See Supported transfer methods for details. By clicking on the subpages on the left menu, you can find the region-specific guides with detailed request field requirements, applicable verification results, and other key considerations.

Step 1: Prepare required beneficiary information

This API accepts beneficiary account details in a similar but simplified structure as the Create a new beneficiary API. Before verifying a beneficiary, 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 that you Validate a beneficiary first and resolve any errors for the bank_details object or its fields 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. See all possible values below.
- 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. The following fields may be included.
- 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 if available.
- resolved_bank_name: Name of the account-holding financial institution if available.

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 all scenarios except INVALID and account name FULL_MATCH, there is an additional risk of misdirected transfers. While you can still transfer to such accounts at your own discretion, we strongly recommend that you double-check all details with your intended beneficairy, as funds sent to the wrong account might be impossible to recover.

Supported transfer methods

Region	Transfer method	Verification source	Name matching supported
United Kingdom	GBP LOCAL (FASTER_PAYMENTS, CHAPS)	Confirmation of Payee (CoP)	Yes
Viet Nam	VND LOCAL	NAPAS	Yes
Australia (Upcoming)	AUD LOCAL (NPP, BECS)	Confirmation of Payee (CoP)	Yes
Europe (Upcoming)	EUR LOCAL	Verification of Payee (VoP)	Yes

Was this page helpful?