Overview

This guide will walk you through the process of managing bank status for Lean's IBAN Account Verification product:

1. Webhook notifications when a bank changes status
2. Retrieving the status of banks
3. Lean' Dashboard so you can check and change the bank availability

Webhook notifications when bank changes status

Whenever Lean or you decide to change the availability of a bank, Lean will send a webhook:

{
  "payload": {
	  "country_code": "SA",
	  "bank_code": "80",
	  "availability": {
			"global": "enabled", // globally enable/disable the bank
			"account_type": {
				"personal": {
					"match": "enabled",
					"no_match": "enabled"
				},
				"freelancer": {
					"match": "enabled",
					"no_match": "enabled"
				},
				"business": {
					"match": "enabled",
					"no_match": "enabled"
				}
			}
		}
  },
  "type": "iban_account_verification.bank.availability.updated",
  "message": "IBAN account verification bank availability has been updated",
  "timestamp": "2021-12-14T15:06:46.083515Z",
  "event_id": "103586d6-e88c-40ba-aa0e-c6ee255aaf2e"
}

You will be able to identify the bank by using the bank_code field. This corresponds to digits 5 and 6 of your customer's IBAN.

A bank can be disabled globally, which means that whenever you call the IBAN Account Verification API for an IBAN corresponding to that bank, you will get an error. Depending if it was you or Lean that disabled it, you will get DISABLED_BY_CLIENT or DISABLED_BY_LEAN respectively. Banks can also be disabled partially by account_type (personal, freelancer and business) and match_type (match, no match). For example, you might receive the following webhook payload:

{
  "country_code": "SA",
  "bank_code": "80",
  "availability": {
    "global": "enabled",
    "account_type": {
      "personal": {
        "match": "disabled", // this is the only disabled field
        "no_match": "enabled"
      },
      "freelancer": {
        "match": "enabled",
        "no_match": "enabled"
      },
      "business": {
        "match": "enabled",
        "no_match": "enabled"
      }
    }
  }
}

The webhook above means that whenever you make an API call to IBAN Account Verification with an IBAN bank corresponding to code 80, if the IBAN corresponds to an account belonging to an individual (personal account) and Lean receives a response iban_ownership_verified=true, then you will receive an error instead of the response. For any other case, such as corporate and freelancer IBANs, you will receive the response.

The reason why we provide such granularity is that sometimes a bank will be providing a correct response for one type of account but not for others. Moreover, sometimes the bank might be responding correctly for one type of response (e.g.: match responses) but might be unreliable for the other response type (e.g.: no match) so Lean will disable only the latter.

Retrieve the status of banks

You can call the IBAN Account Verification bank API to check which banks are supported and which have been disabled either by you or Lean.

Dashboard to manage status

You can log into the Lean Dashboard to check the status and enable / disable a bank. Whenever you enable / disable a bank you receive a webhook as explained before.