BAV (VoP) API

Part of the Bank Account Verification service. One request asks the bank that holds an IBAN whether the name you send is the name on that account. The bank answers through the Verification of Payee scheme, and the API returns its verdict, yes, partial, no or unavailable, together with the bank’s BIC. Use it before you pay a new beneficiary, to catch typing errors and misdirected payments while they can still be corrected. Accounts in 21 countries can be verified.

Endpoint

• HTTPS, POST only; GET, HEAD and OPTIONS are refused with 405 (so there is no CORS preflight: call the API from your server, not from a browser). The key goes in the x-api-key header, the input in a JSON body with Content-Type: application/json. There is no GET form and no form-encoded form.
• The HTTP status tells you whether a verification was carried out. 200: the request reached the bank and the outcome, including partial match, no match and unavailable, is in the body. 400, 401, 405, 415, 500: the request was refused, the body is just {"error":"CODE"}; no bank was contacted, except for INTERNAL_SERVER_ERROR:UNERSP, where the request to the bank network failed. 429: rejected by the rate limit (see Rate limits).
• Responses are UTF-8 JSON, Content-Type: application/json; charset=UTF-8 (the 405 and 415 refusals send application/json without the charset).
• A verification can take a while: the answer comes from the bank, and some banks are slow. Allow at least three minutes before giving up on a request (see Response times).
• One query from your BAV balance is used once the request has passed the account checks and the IBAN’s bank has been identified: every 200 response, the check-digit refusal INVALID_IBAN_CHECKSUM and INTERNAL_SERVER_ERROR:UNERSP use one; everything refused before that point (the other 400s, 401, 405, 415, 429, INTERNAL_SERVER_ERROR:BNFDBS) uses none.
• The service may be used only with payment intent: verify a payee because you are about to pay them, not to screen lists of accounts. See the terms of service.
• Submitted IBANs and names and the answers to them are kept only in our technical logs, for troubleshooting.

Your first request

Start with the sandbox: same API, fixed answers, nothing charged.

curl "https://sandbox.iban.com/clients/api/verify/v3/" -H "x-api-key: testkey" -H "Content-Type: application/json" -d '{"IBAN":"FR7630006000011234567890189","name":"John Doe"}'

The answer:

{
   "query": {
      "IBAN": "FR7630006000011234567890189",
      "name": "John Doe",
      "success": true
   },
   "result": {
      "valid": true,
      "name_match": "yes",
      "bic": "AGRIFRPPXXX"
   },
   "error": ""
}

Then switch the host to api.iban.com and the key to yours. Each verification there is real, answered by the account’s bank, and uses one query. Requests in seven languages are under Example request.

Keeping the key safe

• Send the key only in the x-api-key header, never in the URL: headers are not written to proxy, load-balancer and web-server access logs, query strings are.
• Call the API from your server. A key embedded in browser JavaScript or a mobile app can be read from the source or the network traffic, and every verification made with it is charged to you.
• Restrict the key to the IP addresses of your servers under Settings; requests from anywhere else are refused with IP_NOT_ALLOWED.
• Keep the key out of source control; load it from an environment variable or a configuration file. A key cannot be regenerated from the client area: if it is exposed, contact support to have it replaced.

Request

Headers

Body

A JSON object with two fields. Other fields are ignored.

Supported countries

IBANs of these 21 countries can be verified. Any other country code is refused with COUNTRY_NOT_SUPPORTED before the bank is contacted, so it costs nothing to try.

Example request

Every example verifies the same account: the published donation account of the German Red Cross, DE63370205000005023307, held by Deutsches Rotes Kreuz e.V. Its response is shown in the next section. Replace YOUR_API_KEY with the key from API Access. Each run is a real verification and uses one query; to try the code for free, point it at the sandbox.

curl "https://api.iban.com/clients/api/verify/v3/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"IBAN":"DE63370205000005023307","name":"Deutsches Rotes Kreuz e.V"}'

<?php
$ch = curl_init('https://api.iban.com/clients/api/verify/v3/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 180,
    CURLOPT_HTTPHEADER     => ['x-api-key: YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['IBAN' => 'DE63370205000005023307', 'name' => 'Deutsches Rotes Kreuz e.V']),
]);
$result = json_decode(curl_exec($ch), true);   // the whole response as an array
curl_close($ch);

echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL;

import json
import requests

r = requests.post('https://api.iban.com/clients/api/verify/v3/',
    headers={'x-api-key': 'YOUR_API_KEY'},
    json={'IBAN': 'DE63370205000005023307', 'name': 'Deutsches Rotes Kreuz e.V'},
    timeout=180)
result = r.json()   # the whole response as a dict
print(json.dumps(result, indent=3))

fetch('https://api.iban.com/clients/api/verify/v3/', {
  method: 'POST',
  headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ IBAN: 'DE63370205000005023307', name: 'Deutsches Rotes Kreuz e.V' }),
})
  .then(res => res.json())
  .then(result => console.log(JSON.stringify(result, null, 3)));   // result: the whole response as an object

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class BavApi {
    public static void main(String[] args) throws Exception {
        String body = "{\"IBAN\":\"DE63370205000005023307\",\"name\":\"Deutsches Rotes Kreuz e.V\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.iban.com/clients/api/verify/v3/"))
            .timeout(Duration.ofSeconds(180))
            .header("x-api-key", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());   // the whole JSON response; parse it with Jackson or Gson
    }
}

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Text.Json.Nodes;

var client = new HttpClient { Timeout = TimeSpan.FromSeconds(180) };
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var content = new StringContent("{\"IBAN\":\"DE63370205000005023307\",\"name\":\"Deutsches Rotes Kreuz e.V\"}", Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.iban.com/clients/api/verify/v3/", content);
var result = JsonNode.Parse(await response.Content.ReadAsStringAsync());   // the whole response
Console.WriteLine(result?.ToJsonString(new JsonSerializerOptions { WriteIndented = true }));

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"time"
)

func main() {
	body, _ := json.Marshal(map[string]string{"IBAN": "DE63370205000005023307", "name": "Deutsches Rotes Kreuz e.V"})
	req, _ := http.NewRequest("POST", "https://api.iban.com/clients/api/verify/v3/", bytes.NewReader(body))
	req.Header.Set("x-api-key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")
	client := &http.Client{Timeout: 180 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]any // the whole response
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		panic(err)
	}
	out, _ := json.MarshalIndent(result, "", "   ")
	fmt.Println(string(out))
}

Response

A completed verification returns three members: query (what you sent), result (the bank’s answer) and error (the status code of the verification, empty for a match). The response to the example request, a match:

{
   "query": {
      "IBAN": "DE63370205000005023307",
      "name": "Deutsches Rotes Kreuz e.V",
      "success": true
   },
   "result": {
      "valid": true,
      "name_match": "yes",
      "bic": "BFSWDE33XXX"
   },
   "error": ""
}

Partial match

The Italian Red Cross, sent as Associazione della Croce Rossa Italiana – ODV, the form published on its website; the bank holds the name slightly differently. error carries NAME_PARTIAL_MATCH while query.success stays true:

{
   "query": {
      "IBAN": "IT12T0623003204000030737371",
      "name": "Associazione della Croce Rossa Italiana – ODV",
      "success": true
   },
   "result": {
      "valid": true,
      "name_match": "partial",
      "bic": "CRPPIT2PXXX"
   },
   "error": "NAME_PARTIAL_MATCH"
}

No match

The German Red Cross account again, with the name John Doe. name_match is no, error is NAME_NOT_MATCH and valid is false: the account exists, as the first example shows, but the IBAN and this name are not a valid pair:

{
   "query": {
      "IBAN": "DE63370205000005023307",
      "name": "John Doe",
      "success": true
   },
   "result": {
      "valid": false,
      "name_match": "no",
      "bic": "BFSWDE33XXX"
   },
   "error": "NAME_NOT_MATCH"
}

Name could not be checked

A French foundation’s account: the name could not be checked. name_match is unavailable, valid is true and error is empty:

{
   "query": {
      "IBAN": "FR7630027174110002636660114",
      "name": "Fondation pour le Logement des Défavorisés",
      "success": true
   },
   "result": {
      "valid": true,
      "name_match": "unavailable",
      "bic": "CMCIFRPPXXX"
   },
   "error": ""
}

Refused request

A refused request has neither query nor result, only the code. The IBAN of the example with its last digit changed:

{"error":"INVALID_IBAN_CHECKSUM"}

Recorded verifications

The responses on this page were recorded on 8 October 2026 against published donation accounts of charities, with the account holder name exactly as each organisation publishes it, and once with a wrong name:

The API does not return the name the bank holds, only the verdict.

Response codes

Every code is an upper-case string in the error field. The HTTP status separates the two kinds: a refused request (nothing was sent to a bank; nothing charged except INVALID_IBAN_CHECKSUM) and a completed verification with a status.

Refused requests

Completed verifications

HTTP 200, with query and result present and query.success true. One query is used. The first four rows were recorded; the last three follow the API source and were not observed during testing.

Handling errors

What each outcome means for your code. A verification is answered by a bank, so the same input can give a different answer at a different time (a bank that was unreachable comes back, an account is renamed); the input errors, on the other hand, are deterministic.

Reading the result

Decide on result.name_match and error, never on the HTTP status alone: a 200 response can say that the name does not match.

• Match (yes): the name you sent is the name on the account. The payment can go ahead.
• Close match (partial, NAME_PARTIAL_MATCH): the bank judged the names to differ only slightly: a middle name, an initial, an abbreviation, a legal-form suffix such as ODV, e.V. or Ltd. The scheme lets the bank disclose the name it holds in this case, but this version of the API does not return it; ask the payer to confirm the name before paying.
• No match (no, NAME_NOT_MATCH): the account exists but is held under a different name. Common causes: a trade name instead of the legal company name, a spelling that differs between the local language and an English rendering, a wrong IBAN that happens to be valid. Do not pay without checking with the payee.
• Unavailable (unavailable): no verdict. With VERIFICATION_NOT_SUPPORTED or VOP_REQUEST_FAILED (valid null) the name could not be checked; with an empty error (valid true) the bank network answered without a name verdict. Causes: the bank is not reachable or does not take part in the scheme; the bank’s system timed out, is overloaded or in maintenance; a problem in the scheme’s infrastructure; the account is closed, blocked or not found; the account is of a kind that is outside the scheme (savings, loan, card, investment and escrow accounts). The name is unverified, not wrong.
• result.valid says whether the IBAN and the name are a valid pair: false means the bank holds a different name for the account. It does not say that the account exists or is open; a pair that could not be checked is null, a verdict-less answer true, so read it together with name_match and treat only yes as verified.
• Send the name the account is held under. For a company that is the legal name from the register, including the legal form; for a person, first and last name as registered with their bank. Titles, “c/o” lines and department names lower the chance of a match.
• Verify immediately before the payment, once. The answer is the bank’s view at that moment, and each completed verification uses one query.

Sandbox

A copy of the API with fixed answers for development and automated tests. It contacts no bank, needs no subscription and uses no queries. Same request format, same JSON bodies, same error codes.

Use the key testkey. The answer depends on the IBAN, the name and the key:

IBANs are matched exactly after spaces are removed (the fixture in lower case is “any other IBAN”); SANDBOX_NOT_SUPPORTED_IBAN exists only on the sandbox.

The request-format errors (MISSING_API_KEY, INVALID_API_KEY, UNSUPPORTED_FORMAT, INVALID_JSON, MISSING_INPUT_IBAN, MISSING_INPUT_NAME, METHOD_NOT_ALLOWED) behave exactly as in production. The sandbox has no fixture for no or unavailable; test those paths with a mocked response.

Response times

• A refused request is answered in about 0.1 s.
• A completed verification takes as long as the bank takes. The recorded verifications took between 0.3 s (Germany) and 3.0 s (United Kingdom); banks answer quickly as a rule, UK banks are the slowest, and the scheme allows a bank up to three minutes. Set the client timeout to at least 180 s, and do not hold a web request open for it: verify in the background and tell the user when the answer is in.
• A request that timed out on your side may still have been completed by the bank and charged.

Checking your balance

The services endpoint returns every service on your account with its remaining queries and expiry date, the same information as My Services. Poll it from your monitoring to catch a low balance before the API starts answering 401 NO_CREDITS_AVAILABLE. It takes your api_key and a format (json or xml) and does not use a query.

The response, shortened to the entry of this service (the endpoint lists every service on your account, one object each):

{
   "services": [
      {
         "service_name": "BAV (2,500 queries)",
         "credits": 52,
         "expiry_date": "2027-05-15",
         "service_expired": 0
      }
   ],
   "errors": []
}

<?xml version="1.0"?>
<result>
   <services>
      <service>
         <service_name>BAV (2,500 queries)</service_name>
         <credits>52</credits>
         <expiry_date>2027-05-15</expiry_date>
         <service_expired>0</service_expired>
      </service>
   </services>
   <errors/>
</result>

The HTTP status is 200 in every case. With a wrong key, services is empty and errors carries code 301 ({"services":[],"errors":[{"code":"301","message":"API Key is invalid"}]}); without format the body is empty.

Rate limits and queries

• The shared API accepts up to 20 requests per second. Above that, requests are rejected with HTTP 429 Too Many Requests before they reach the API: not processed, not charged. Acceptance resumes as soon as your rate drops below the limit, so wait a moment and resend; keep the sending rate at or below 20 per second with a queue or a token bucket. If several processes send requests, apply the limit to their total.
• Each completed verification (HTTP 200) uses one query, whatever the outcome, and so do INVALID_IBAN_CHECKSUM and INTERNAL_SERVER_ERROR:UNERSP; requests refused before the bank is identified use none. Your balance and expiry date are shown under My Services and by the services endpoint.
• Need more throughput? A dedicated API server is available for your account with no per-second limit, on its own hostname. Contact support with your expected volume.

Glossary