Bank Account Verification Integration Process

Bank Account Verification (BAV) works by you specifying certain account details, together with the associated user information you have on record, to the Stitch API.

Integration Overview

Bank Account Verification is protected by a client token. You'll need to follow the steps described in the client token guide to obtain a client token with the client_bankaccountverification scope.

Once you have a valid client token, you can run the GraphQL verifyBankAccountDetails query to verify the user's bank account details, with inputs as per the BankAccountVerificationInput type. The GraphQL API URL https://api.stitch.money/graphql can be used for all verification requests (whether on test or live clients).

The VerifiedBankAccountDetails response from this call indicates to you whether the account is verified. A further breakdown of exactly which information is verified, and which is not, is also included.

Verifying a Bank Account

For all verification requests, required fields include:

• Bank account being verified, specifically:
  • Number of the account being verified, in the accountNumber input,
  • Bank ID for the account being verified (as mapped from this enum list), in the bankId input,
• Account holder details being verified against, specified within the accountHolder input. This should contain one of the following:
  • A 13-digit ID number, for SA individuals, or
  • A passport number and country, for foreign individuals, or
  • A business registration number, for businesses.

Certain fields, on the other hand, are optional:

• The corresponding universal branch code for the bank ID provided is used as the default when verifying. However, if you do have a branch code and wish to verify with this, you may specify this in the branchCode field within the query inputs.
• The account type is not required, but will be verified if provided in the accountType input field.
• Individual initials, last/family names and business names are not required, but will be verified if provided.

Country codes

When specifying country codes related to identity/business information of the user, the 2-character ISO country code should be specified.

Supported banks

All supported banks for verification are listed here. This value is specified within the bankId field (of type BankAccountVerificationBankIdInput).

Based on the extent of your user base and the information captured on your platform, different user information may be required. The following examples indicate how different types of user accounts should be verified:

Individual (Local) Account

For South African users, you may verify bank accounts against South African identity document information. Within the accountHolder.individual input, the identifyingDocument.identityDocument field (of type IdentityDocumentInput) should be specified, as shown in the example query below:

Open in IDE ↗

Individual (Foreign) Account

For foreign users owning South African bank accounts, you may verify bank accounts against passport document information. In this case, the accountHolder.individual input should be modified to include the identifyingDocument.passport field (of type PassportInput), as shown in the example query below:

Open in IDE ↗

Business Account

For business accounts, you may verify bank accounts against business registration information. This should be specified within the accountHolder.business field, as shown in the example query below:

Open in IDE ↗

Interpreting Verification Results

Verification results are represented by fields of the VerificationResult type. 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 failed to match the data provided by the verification system, or the field itself is invalid or non-existent.
• unknown: Verification could not be performed conclusively for the 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.

High-level Verification Results

An overall, combined verification result is provided in the response, in the accountVerificationResult field. This will be verified if the account is valid and open, and the identity (or business registration) number and family (or business registered) name are all successfully verified.

Detailed Verification Results

A breakdown of exactly what information passed and failed verification is included within the detailedAccountVerificationResults field. All sub-fields are of the VerificationResult type. These fields are:

• accountExists: Indicates whether the account exists at the bank.
• identityDocumentMatch: Indicates whether the individual's identity number, or business' registration number, matches that of the accountholder.
• initialMatch: Indicates whether the individual's initial matches that of the accountholder. Note that this field does not apply to business account verification.
• lastNameMatch: Indicates whether the individual's last name, or business' registered name, matches that of the accountholder.

Other Account Information

A few additional insights on the account, and its usage, are provided if required.

• accountTypeVerificationResult: Indicates whether the account type was verified successfully, if this was provided in the request.
• accountOpen: Indicates whether the account is still open at the bank.
• accountOpenForMoreThanThreeMonths: Indicates whether the account has been open for longer than three months.
• accountAcceptsCredits: Indicates whether the account accepts credit payments i.e. the account is able to be paid to. Note that in the case of frozen accounts, this will be false.
• accountAcceptsDebits: Indicates whether the account accepts debit payments i.e. the account is able to make payments. Note that in the case of frozen accounts, this will be false.
• accountHolder: Contains the account holder information as per the verifier. This is a VerifiedAccountHolderBankAccountDetails field.

Handling Pending Verification Responses

In some cases, the verification provider may take up to 120 seconds to verify bank account verification, depending on the bank selected. In these cases, our API will return an error including the RESULT_PENDING extension code, to indicate your verification request is pending:

{
  "errors": [
    {
      "message": "Your query has been submitted, but the results are still pending. Please try again later.",
      "locations": [
        {
          "line": 8,
          "column": 11
        }
      ],
      "path": ["client", "verifyBankAccountDetails"],
      "extensions": {
        "code": "RESULT_PENDING"
      }
    }
  ],
  "data": null
}

When receiving this response, you may resubmit the same query, with the same inputs, to check if we have received a response yet. Results will be stored for up to 48 hours following the initial request, so you will not be billed for subsequent lookups of the same data within this period.

Simulating Verification Results

When integrating with your test client, mock information can be specified over the API to simulate verified / refuted results.

To simuate a successful individual account verification, the following should be included in your test query:

Parameter	Value
initials	J
familyName	Clegg
identifyingDocument.identityDocument.number	5306075800082
identifyingDocument.identityDocument.country	ZA
accountNumber	Any account number ending in 0

For a similarly successful business account verification, the following should be included in your test query:

Parameter	Value
name	Johnny Clegg Recordings Ltd
registration.number	1234/567891/23
registration.country	ZA
accountNumber	Any account number ending in 0

Note that varying the data inputs from the above mock data values will result in refuted results being returned for the changed data fields.

The RESULT_PENDING error may be returned from any queries in the test environment. This is to simulate the random occurrences that may be expected from this in the live environment. On receiving this error, you may resubmit your query to immediately receive a verification response.

Postman Collection

Bank Account Verification requests can be created and tested using the Postman collection available here. These can be used by specifying your client credentials and supplying the custom request variables where required.