Financial Data

7.2. Bank Account Verification Service

Bank account verification allows a client to verify that a bank account belongs to a particular user without requiring them to link their bank accounts with Stitch.

This feature can be useful when you already have bank account information provided by a user, but verification is required to ensure that the bank account is valid and indeed 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.

In order to verify bank account details, a GraphQL query is needed that provides information about the user and their bank account for verification.

The required fields here are a bank account number, a bank ID and account holder details with either an ID number or passport for individuals or business registration number for businesses. Account type is only required if you want to verify the account type against the account too.

If the branch code is not provided, the universal branch code for the bank will be used.

Interpreting the results

Verification results are represented by fields with the VerificationResult type. The possible values for this type is 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 the field. This could be because the information requested is not available on the bank's system, the verification systems are unavailable or that it is not supported for the bank specified.

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 response 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. You can generate your own here.
  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:

Valid Simulated Individual Identity


There is also a simulated business identity to test against:

Valid Simulated Business Identity

nameJohnny Clegg Recordings (Ltd.)

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.

Here is an example query using the individual data from the table above: