Introduction

The Account Verification Services allow you to check account ownership, confirming whether your customer is the owner of a bank account.

Account Verification (Entity)

Where a customer has connected their account through Lean Open Banking you can confirm account ownership using our Account Verification endpoint by providing the Entity ID for your connected customer and an identifier. This can be used to verify account ownership for personal, business and freelancer accounts.

Get list of IBANs

Using our Account Verification (Entity) you will also be able to get a list of all linked IBANs that belong to the customer Entity ID. You can then confirm these IBANs are owned by your customer without them needing to provide these IBANs manually.

Account Verification (IBAN)

Where you are not using Open Banking or a customer has not connected their account via Open Banking you can confirm account ownership using our Account Verification endpoint by providing an IBAN and an identification number or the customers full name.

With IBAN Account Verification we will confirm whether the details provided match and this customer owns the related IBAN or not. This can be used to verify account ownership for personal, business and freelancer accounts.

The response will return whether the account is verified with a true or false response to 'iban_ownership_verified'. Where the response is 'true' this means it is a match and the account ownership has been verified. Where the response is 'false' this means it is a no match and the account has not been verified.

Please note the IBAN verification is a universal API using the same endpoint as ourUAE Account Verification Service for IBANs.

Using the Account Verification (Entity) API

To use the Account Verification (Entity) API you will need to call the endpoint sandbox.sa.leantech.me/verifications/v2/entity. It is important to note your customer must have connected their bank account an the Entity created with accounts, identity and identities permissions (at least) before you make a call to the Account Verification API.

To learn more about creating an entity, please read theCreating an Entity guide.

To make a request you will need to provide;

• an identification for your customer;
  • When checking a person you will need to provide an object in the array with type=NATIONAL_ID and the NID or Iqama of your customer in the value field
  • When checking a business, one object will have type=COMMERCIAL_REGISTRATION and the CR of your customer in the value field and the other object will have type=UNIFIED_NUMBER and the UNN of your customer (starts with 7) in the value field
• entityID for your connected customer

The response will return whether the account is verified (true or false), determining whether your customer owns the associated account.

Testing Account Verification (Entity) API in sandbox

To test in sandbox you will need the following identifications input and an entity ID.

Entity ID

An entity_id for an entity you have created with a mockbank with permissions accounts

Identifications

Note, any other combination of valid identifications parameters will still give a list of IBANs but they will be marked as NOT belonging to the customer.

Get list of IBANs

From within the Account Verification (Entity) API the response will contain the IBANs found in the bank account in the array ibans. To determine if these IBANs belongs to your customer, you can check in the response if the value for each of them for iban_ownership_verified is true or false.

Using the Account Verification (IBAN) API

To use the Account Verification (IBAN) API you will need to call the endpoint sandbox.sa.leantech.me/verifications/v2/iban. This API supports personal, freelancer and business bank accounts in KSA from any bank connected to SARIE.

To make a request you will need to provide;

📘

For the business case, the API will not work if only CR or UNN is provided (both need to be provided).

For the freelancer case, the API will not work if only freelancer number or national ID / Iqama are provided (both need to be provided).

To determine if the IBAN belongs to your customer, you can check in the response if the value for iban_ownership_verified is true or false.

The possible values for iban_ownership_verified are as follows:

To ensure you are aware and can act upon the availability of banks, please read the relevant guide.

Note an inactive account status is closed, blocked or in liquidation

Response Codes & Handling

To implement the best-in-class solution for the IBAN verification flow, you need to implement a fallback mechanism in case the API fails for any reason (mostly technical/maintenance issues). And if you currently don't have a validation mechanism, the fallback can be either flagging the customer as "unverified" for a manual check later (by an agent) or maybe asking for a manual IBAN Certificate upload.

In terms of the different response codes and how to handle the fallback flow for each code, it should be done as follows:

1. status is OK - This means the API call is successful:
   1. iban_ownership_verified is true - Account ownership confirmed. Customer owns the account. You can allow them to use this IBAN
   2. iban_ownership_verifiedis false - Account ownership not confirmed. Customer does not own the account. You should ask them to provide a new account
      1. For this scenario, you can also look at the account_status in the response which reflects the IBAN’s status. The account might be BLOCKED, INACTIVE or IN_LIQUIDATION which means the customer cannot use the account/IBAN and that’s why a false response is returned
2. status is FAILED - This means the API call failed and you should look at the granular_status_code for more info:
   1. Retriable error:
      1. BANK_ISSUE or LEAN_ERROR - There might be connection errors or issues reaching the API
      2. These errors can be retried. But if the error persists, you should raise it to Lean’s support team and fallback to the manual IBAN certificate/letter upload
   2. Non-retriable errors:
      1. UNSUPPORTED_BY_BANK - Provided IBAN belongs to an unsupported bank (the supported banks are all the banks connected to SARIE)
      2. DISABLED_BY_LEAN or DISABLED_BY_CLIENT - Provided IBAN belongs to a bank that’s currently disabled by Lean (mainly for maintenance) or by the client (in case you want to disable the access to a certain bank - which you can do from the Developer Portal)
      3. For these types of errors, you should fallback to a manual flow by asking your customer to provide the IBAN certificate/letter so you can validate the ownership

Testing Account Verification (IBAN) API in sandbox

You can test the Account Verification (IBAN) API using the various identifications types below an with the following details.