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.
- 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.
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:
- Ensure you are using a test client.
- Make the bank account verification query with any details.
- 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.
Business Account Holder
An example of verifying account details for a business account holder.
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. |