Bank Account Verification

The Bank Account Verification Service (BAVS) allows a client to verify that a bank account belongs to a particular user without requiring them to link their bank account with Stitch.

This feature is useful when you already have the user's bank account information but require verification to ensure that the bank account is valid and belongs to the user.

Verifying Bank Account Details

If you would like to use the bank account verification feature, you will need to request to have it enabled on your client. This query requires a client token with the client_bankaccountverification scope. For more information on how to obtain these, please see the client token guide.

Once you have a valid client token, you can run the below GraphQL query to verify the user's bank account details. The required fields for the query are:

• Bank account number.
• Bank ID (please refer to the BankAccountVerificationBankIdInput enum list for the list of valid bank ID values).
• Account holder details with either:
  • An ID card or passport number for individuals.
  • A business registration number for businesses.

Optional Fields

• If the branch code is not provided, the universal branch code for the bank will be used.
• Account type is only required if you also want to verify the account type against the account.

Open in IDE ↗

Interpreting the Results

Verification results are represented by fields with the VerificationResult type. The possible values for this type are as follows:

• verified: The data provided was successfully verified against the bank data.
• refuted: The data provided is not correct. It negatively correlates with the data provided by the verification system, or the field itself is invalid or non-existent.
• unknown: Verification could not be performed for this field. This could be because the information requested is not available on the bank's system, the verification systems are unavailable, or it is not supported for the bank specified.

Detailed verification results are represented with the DetailedAccountVerificationResults type. The type contains fields with the VerificationResult type. The fields are as follows:

• accountExists: Result of whether the account exists.
• identityDocumentMatch: Result of whether the user's identity number matches that of the account-holder. When a company registration number is provides, this field will contain the result of whether the registration number matches that of the business.
• initialMatch: Result of whether the user's initial matches that of the account-holder. This field should be ignored for business account verifications.
• lastNameMatch: Result of whether the user's last name matches that of the account-holder. When a business name is provided, this field will contain the result of whether it matches the business's registered name.

Handling Asynchronous Responses

In some cases the verification provider could take up to 120 seconds to verify bank account verification, depending on the bank selected. In this case our API will return a RESULT_PENDING error code to indicate your verification request is pending. Submitting the same query again will check whether we have received a response yet and incur no further fee.

The results are stored for up to 48 hours after the initial request is made, and you won't be billed for subsequent lookups of this data within this retention period.

Using the Simulated Verification

When using a test client, a simulated version of the verification provider is called to allow testing without incurring verification costs. The simulated response will randomly follow the asynchronous response flow, but the response is available immediately when resending the same request.

The VerificationResult type of requests made from a simulated environment is non-deterministic and random, to mimic the response you might encounter in a production environment.

To use this simulation:

1. Ensure you are using a test client.
2. Make the bank account verification query with any details.
3. When a RESULT_PENDING error code is returned, make the query again with the same details.

In order for you to get the most out of the simulation we have prepared a fake individual identity to test against:

Parameter	Value
familyName	Clegg
initials	J
identifyingDocument.identityDocument.country	ZA
identifyingDocument.identityDocument.number	5306075800082

There is also a simulated business identity to test against:

Parameter	Value
name	Johnny Clegg Recordings Ltd
registration.country	ZA
registration.number	1234/567891/23

For the purposes of testing, you are welcome to use any account number. Account numbers that end with a 0 will return a positive validation, and account numbers that end with a 1 will return a negative validation.

Furthermore, changing any of the other parameter values from the values in the above table will result in a negative validation for the changed field. If all the information is the same as the prepared fake identity, the simulation will respond with a positive validation.

Individual Account Holder

An example of verifying account details for an individual account holder.

Open in IDE ↗

Business Account Holder

An example of verifying account details for a business account holder.

Open in IDE ↗

Verification Error Reasons

This table describes possible reasons you may encounter with the VERIFICATION_ERROR error:

Value	Description
invalid_account_type	The provided bank account type is invalid.
technical_error	An error occurred while making the verification request.
invalid_branch_number	The provided bank branch code is invalid.
invalid_account_number	The provided bank account number is invalid.
instituition_not_supported	Verification of provided bank is not supported.
invalid_account_number_length	The provided bank account number length is invalid.
bond_account_not_allowed	Verification of bond accounts is not supported.