BAV Service API Docs

1. Introduction

This API is part of the BAV service.

Bank Account Verification or BAV for short is a service providing an API for verification of bank accounts within the issuing bank. This service checks whether the bank account exists with the issuing bank, is active, and matches the owner name you provide.

Endpoint URLs

The Sandbox API endpoint is: https://sandbox.iban.com/clients/api/verify/v3/

The production API endpoint is: https://api.iban.com/clients/api/verify/v3/

Supported Countries

Currently, the BAV Service supports verification of payee for the countries below.

  • AustriaAT
  • BelgiumBE
  • CyprusCY
  • GermanyDE
  • EstoniaEE
  • SpainES
  • FinlandFI
  • FranceFR
  • GreeceGR
  • CroatiaHR
  • IrelandIE
  • ItalyIT
  • LithuaniaLT
  • LuxembourgLU
  • LatviaLV
  • MaltaMT
  • NetherlandsNL
  • PortugalPT
  • SloveniaSI
  • SlovakiaSK

2. Request

HTTP Method

The API supports HTTP POST requests.

Request Headers

To authenticate you as our client, you need to send the API key in the headers of the request.

Parameter Value Required Description
x-api-key YOUR_API_KEY Required Your personal API key required to authenticate you with the service.
Content-Type application/json Required The API only accepts application/json content type

Request Body

Request body is provided in JSON format and must contain the following elements.

Parameter Type Required/Optional Description
IBAN string Required The International Bank Account Number .
name string Required The first and last name of the account owner. Example: John Doe
This parameter is used to perform name matching verification.

Example Requests

Verification request of Personal account for France (FR): 
curl "https://api.iban.com/clients/api/verify/v3/" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key:[YOUR_API_KEY]" \
  -d '{
        "IBAN":"FR7630006000011234567890189",
        "name":"John Doe"
      }'

3. Response

Response Format

The API returns a JSON object with the following fields:

Response schema
Field Type Example Description
query object … Echo of the request parameters and lookup outcome.
query.IBAN string FR7630006000011234567890189 IBAN used for the check.
query.name string John Doe Account holder name provided in the request.
query.success boolean true Whether the lookup completed without transport/processing errors.
result object … Verification outcome for the provided inputs.
result.valid boolean true If the issuing bank confirmed the validity of this IBAN.
result.name_match string "yes" Match status between provided query.name and the account name. Example statuses include "yes", "no", "partial", "unavailable".
result.bic string HABALT22XXX BIC/SWIFT of the bank which issued this IBAN.
error string "" Error message if query.success is false; empty string when no error. See section 5. Error Handling

Example Response

Example response for France(FR)
{
  "query": {
    "IBAN": "FR7630006000011234567890189",
    "name": "John Doe",
    "success": true
  },
  "result": {
    "valid": true,
    "name_match": "yes",
    "bic": "AGRIFRPPXXX"
  },
  "error": ""
}

4. Response timing

API response times may vary depending on the country/provider.

Response time depends on the country and bank which needs to return the result. We observed response times from 200 milliseconds to 3 minutes.

5. Error Handling

If an error occurs during the request, the API may return an appropriate HTTP status code along with an error response in the JSON format. Common error fields may include:

HTTP Status Message Cause/Solution
400 MISSING_API_KEY You need to send the API key within the header of your http request.
415 UNSUPPORTED_FORMAT The content-type header must be application/json.
400 INVALID_JSON The request body must be a valid JSON structure.
400 MISSING_INPUT_IBAN International Bank Account Number must be provided in the request body
400 MISSING_INPUT_NAME Name of the account owner must be provided for match verification to be performed.
401 INVALID_API_KEY You must provide a valid API key to identify your account with the API.
401 IP_NOT_ALLOWED You have enabled IP access restriction in your account. You need to allow access for the IP address of the server which is making the request.
401 USER_NOT_ALLOWED Your account does not have access to this service. You need to purchase a license/subscription.
401 SUBSCRIPTION_EXPIRED The service plan has expired. You need to renew your subscription from your Client Area -> My Services section.
401 NO_CREDITS_AVAILABLE The pre-loaded credits in your service plan have been exhausted. You need to refill your plan by purchasing another package from your Client Area -> Pricing section.
400 INVALID_IBAN_CHECKSUM The checksum of the IBAN sent for validation is not correct. This could indicate a syntax error. This IBAN is not valid.
400 COUNTRY_NOT_SUPPORTED The country code of the IBAN is not part of the supported countries by the Verification of Payee network. See Supported Countries
500 INTERNAL_SERVER_ERROR An unexpected internal error occurred in our system. Please contact support.
200 VERIFICATION_NOT_SUPPORTED The bank responded, however this IBAN/BANK does not support verification of payee check.
200 VOP_REQUEST_FAILED The bank failed to respond to our verification request.
200 NAME_NOT_MATCH The bank responded, but the name does not match the owner of the account.
200 NAME_PARTIAL_MATCH The bank responded, the submitted name does not exactly match, but is a close match of the owner name.
429 Too many requests. Rate limit reached. Our API is rate limited to provide optimal performance. Please throttle your requests.

6. Sandbox Environment

You can use the sandbox API endpoint to test the integration of our BAV API service.

Sandbox endpoint URL: https://sandbox.iban.com/clients/api/verify/v3/

The sandbox API accepts pre-defined input test parameters. You can find the accepted inputs below

API key: testkey
IBAN Name x-api-key Result
FR7630006000011234567890189 John Doe testkey Valid Name Match
DE89370400440532013000 John Doe testkey Valid Name Match
DE89370400440532013000 John testkey Partial name match.
NL91ABNA0417164300 any name testkey VERIFICATION_NOT_SUPPORTED
BR9700360305000010009795493P1 any name testkey COUNTRY_NOT_SUPPORTED
FR7630006000011234567890183 any name testkey INVALID_IBAN_CHECKSUM
ANY any name nomorecredits NO_CREDITS_AVAILABLE
ANY any name serviceexpired SUBSCRIPTION_EXPIRED
ANY any name usernotallowed USER_NOT_ALLOWED
ANY any name ipnotallowed IP_NOT_ALLOWED

Important Notes:

Ensure to handle error responses gracefully and provide appropriate feedback to users.

The service can only be used with payment intent, verifications of payee can only be performed before initiating a payment. Please check with our terms of service before proceeding.