IBAN Validation API V4 Documentation

This API is part of our IBAN Suite service

1. What is new in V4 IBAN Validation API?


We are constantly working to improve our services and to provide better payment validation solutions.
You may have noticed that IBAN Suite API has skipped a version iteration from V2 to V4.
This was done because we have united the other APIs such as SortWare v3 into a single versioning iteration e.g. v4.

Changelog ( from v2 to v4 ):


New validation added ( error 206 and success 006 ) - V4 API now checks for illegal characters in the input IBAN.
The new error code - 206 (Validation Failed) with message: IBAN contains illegal characters.
The success code for this check is - 006 ( Validation Success ) with message: IBAN does not contain illegal characters
This error code will give you more information in the event that you submit an IBAN with non-alphanumeric characters to our system.
Previous behavior was to strip all non-alphanumeric characters and perform the validation

New validation added ( error 207 and success 007 ) - Country does not support IBAN
This validation layer will report if the country code of the submitted IBAN is not part of the official countries supporting IBAN payments.
For example, a person may generate an IBAN for the United States using an unreliable third party software
Such IBAN may look like US64SVBKUS6S3300958879
You will notice that the check digit is correct and it will pass the modulus validations, however it is not a valid IBAN since the United States does not use IBAN for banking payments.


2. Features


The IBAN Validation API V4 allows you to do the following:

  • Validate if an IBAN is valid using it’s check digits
  • Validate if an IBAN has valid domestic bank code and account number check digits *
  • Validate IBAN length for specific country
  • Validate IBAN structure/formatting for specific country
  • Validate IBAN characters ( check for non-alphanumeric characters )
  • Validate if country code supports IBAN standard

  • Identify the bank which issued the IBAN
  • Identify the country and country code of an IBAN
  • Identify address of the bank issued the IBAN
  • Identify bank’s BIC code
  • Identify bank’s SEPA support: B2B,COR1,SCC,SCT,SDD

* Bank Code and Account Number validations are performed for certain banks and countries only.

3. API V4 Requests



The API system allows you to automate IBAN validation via a simple HTTP GET or POST request.
The accepted parameters are listed in the table below:

Field Name Length Type Description
IBAN Max 100 String The IBAN you want to validate.
api_key 128 String Your personal API key.
format 5 String Format of the response XML and JSON supported.
sci 1 int If set to 1, the API will return Sepa Instant Credit Transfer marker in the sepa_data object. Default is 0. Note: SEPA Instant support detection is based on RT1 participants. TIPS participation is not supported.
translit 1 int If set to 1, the API will transliterate all special characters into Latin. This feature is useful if using the output for SEPA payments which do not accept local language characters.
Example:

"bank": "Raiffeisenbank Neukirchen an der Vöckla eGen",
"address": "Hauptstraße 22",
"city": "Neukirchen an der Vöckla",

With parameter "traslit=1" will result in:

"bank": "Raiffeisenbank Neukirchen an der Vockla eGen",
"address": "Hauptstrasse 22",
"city": "Neukirchen an der Vockla",

*To obtain an API key, please contact us at contact@iban.com or purchase a subscription at our order page

EXAMPLE – Validate an IBAN
Feel free to use the sample code below to test the API in the most common programming languages.

curl "https://api.iban.com/clients/api/v4/iban/" \
    -X POST \
    -d format=json \
	-d api_key=[YOUR_API_KEY] \
	-d iban=DE46500700100927353010
<?php
$curl = curl_init();

$post = [
    'format' => 'json',
    'api_key' => '[YOUR_API_KEY]',
    'iban'   => 'DE46500700100927353010',
];

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.iban.com/clients/api/v4/iban/',
	CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => $post
));

$output = curl_exec($curl);
$result = json_decode($output);

print_r($result);

curl_close($curl);
?>
require 'net/http'

uri = URI('https://api.iban.com/clients/api/v4/iban/')

res = Net::HTTP.post_form(uri, "format" => "json", "api_key" => "[YOUR_API_KEY]","iban" => "DE46500700100927353010")

puts res.body
import requests

post_data = {'format':'json', 'api_key':'[YOUR_API_KEY]','iban':'DE46500700100927353010'}

response = requests.post('https://api.iban.com/clients/api/v4/iban/',post_data)
print(response.text)
use LWP::UserAgent;

my $ua = LWP::UserAgent->new;
my $server_endpoint = "https://api.iban.com/clients/api/v4/iban/";

my $format = 'json';
my $api_key = '[YOUR_API_KEY]';
my $iban = 'DE02100500000024290661';


my $req = HTTP::Request->new( POST => $server_endpoint );
$req->content_type('application/x-www-form-urlencoded');

my $post_data = 'format=' . $format . '&api_key=' . $api_key . '&iban=' . $iban;

$req->content($post_data);

my $resp = $ua->request($req);

if ( $resp->is_success ) {
    my $message = $resp->decoded_content;
	print $message;
}

JAVA

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.json.simple.JSONObject;
import org.json.simple.JSONArray;
import org.json.simple.parser.ParseException;
import org.json.simple.parser.JSONParser;


public class ibanapi {

	private final String USER_AGENT = "API Client/1.0";

	public static void main(String[] args) throws Exception {

		ibanapi http = new ibanapi();

		
		System.out.println("\nTesting API - Send API POST request");
		http.sendPost();

	}

	// HTTP POST request
	private void sendPost() throws Exception {

		String url = "https://api.iban.com/clients/api/v4/iban/";
		URL obj = new URL(url);
		HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();

		//add reuqest header
		con.setRequestMethod("POST");
		con.setRequestProperty("User-Agent", USER_AGENT);
		con.setRequestProperty("Accept-Language", "en-US,en;q=0.5");

		String urlParameters = "api_key=[YOUR_API_KEY]&format=json&iban=DE02100500000024290661";

		// Send post request
		con.setDoOutput(true);
		DataOutputStream wr = new DataOutputStream(con.getOutputStream());
		wr.writeBytes(urlParameters);
		wr.flush();
		wr.close();

		int responseCode = con.getResponseCode();
		System.out.println("\nSending 'POST' request to URL : " + url);
		System.out.println("Post parameters : " + urlParameters);
		System.out.println("Response Code : " + responseCode);

		BufferedReader in = new BufferedReader(
		new InputStreamReader(con.getInputStream()));
		String inputLine;
		StringBuffer response = new StringBuffer();

		while ((inputLine = in.readLine()) != null) {
			response.append(inputLine);
		}
		in.close();

		//print result
		System.out.println(response.toString());

	}

}

.NET

public static void Main(string[] args)
		{						
			var request = (HttpWebRequest)WebRequest.Create("https://api.iban.com/clients/api/v4/iban/");
 
			var postData = "api_key=[YOUR_API_KEY]";
			 postData += "&format=json";
			 postData += "&iban=DE02100500000024290661";
			 
			var data = Encoding.ASCII.GetBytes(postData);
			 
			request.Method = "POST";
			request.ContentType = "application/x-www-form-urlencoded";
			request.ContentLength = data.Length;
			 
			using (var stream = request.GetRequestStream())
			{
			 stream.Write(data, 0, data.Length);
			}
			 
			var response = (HttpWebResponse)request.GetResponse();
			 
			var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
			
			Console.WriteLine(responseString);
			
			Console.Write("Press any key to continue . . . ");
			Console.ReadKey(true);
		}

NODE

var request = require('request');

var headers = {
    'User-Agent':       'IBAN API Client/0.0.1',
    'Content-Type':     'application/x-www-form-urlencoded'
}

var options = {
    url: 'https://api.iban.com/clients/api/v4/iban/',
    method: 'POST',
    headers: headers,
    form: {'api_key': '[YOUR_API_KEY]', 'format': 'json', 'iban': 'GB04BARC20474473160944'}
}

request(options, function (error, response, body) {
    if (!error && response.statusCode == 200) {
     
		var data = JSON.parse(body);

		console.log(data.errors);
		
		console.log("Bank Name: " + data.bank_data.bank);
		console.log("Bank BIC: " + data.bank_data.bic);
		console.log("Bank City: " + data.bank_data.city);
		console.log("Bank Address: " + data.bank_data.address);
		console.log("Bank Zip: " + data.bank_data.zip);
		console.log("Bank Phone: " + data.bank_data.phone);
		console.log("Bank FAX: " + data.bank_data.fax);
		console.log("Bank www: " + data.bank_data.www);
		console.log("Bank email: " + data.bank_data.email);
		console.log("Bank Country Name: " + data.bank_data.country);
		console.log("Bank Country Code: " + data.bank_data.country_iso);
		console.log("Domestic Account Number: " + data.bank_data.account);
		
    }
})


An example usage of the IBAN Validation API with a GET request can be found below:

https://api.iban.com/clients/api/v4/iban/?api_key=key&format=xml&iban=IBAN

Where:
  • key is your API key
  • IBAN sent for validation by the API module.
  • xml is the response format. Also a json keyword can be specified for json formatted response.

Once an HTTP GET or POST request is made with the correct API key, the system will return the results in the specified format. You can find an sample response in the next section “API Response Structure”

4. API V4 Response

An XSD Schema of the API’s response can be found below:




	 
		   
				 
					   
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
					   
				 
		   
		   
			
				
					
						
							
								
								
							
						
					
				
			
		
	 



A detailed description of the bank_data object fields returned can be seen in the table below:

Field Name Length Type Description
BIC Max 11 String The BIC code of the issuing bank/branch or institution.
BANK Max 256 String The name of the bank/institution that issued the IBAN
BRANCH Max 256 String Name of the specific bank branch if available
COUNTRY Max 32 String Full name of the country of origin e.g. “United States”
COUNTRY_ISO 2 String Two letter abbreviation of the country code e.g. US, UK, AU, FR … etc.
CITY Max 128 String The name of the city of the issuing bank’s location.
STATE Max 128 String The name of the state in which the bank/branch is located.
ZIP Max 11 String Zip or postal code of the city.
ADDRESS Max 128 String The issuing bank address.
ACCOUNT Max 128 String The domestic bank account number extracted from the IBAN.
A detailed description of the sepa_data object fields returned can be seen in the table below:

Field Name Length Type Description
SCT Max 3 String Whether this bank supports SEPA Credit Transfer.
SDD Max 3 String Whether this bank supports SEPA Direct Debit.
COR1 Max 3 String Whether this bank supports SEPA COR1.
B2B Max 3 String Whether this bank supports SEPA Business to Business.
SCC Max 3 String Whether this bank supports SEPA Card Clearing.


A sample XML reply from the API for a IBAN validation query would be:

	
		BUKBGB22XXX
		CHELTENHAM
		BARCLAYS BANK UK PLC
		
Leicester LE87 2BB 0345 7345345 United Kingdom GB 55555555 BUKB 202015
YES YES YES YES NO 006 IBAN does not contain illegal characters 001 IBAN Check digit is correct 002 Account Number check digit is correct 005 IBAN structure is correct 003 IBAN Length is correct 007 Country supports IBAN standard
The same response in JSON format would look like this:
{
   "bank_data":{
      "bic":"BUKBGB22XXX",
      "branch":"CHELTENHAM",
      "bank":"BARCLAYS BANK UK PLC",
      "address":" ",
      "city":"Leicester",
      "state":null,
      "zip":"LE87 2BB",
      "phone":"0345 7345345",
      "fax":null,
      "www":null,
      "email":null,
      "country":"United Kingdom",
      "country_iso":"GB",
      "account":"55555555",
      "bank_code":"BUKB",
      "branch_code":"202015"
   },
   "sepa_data":{
      "SCT":"YES",
      "SDD":"YES",
      "COR1":"YES",
      "B2B":"YES",
      "SCC":"NO"
   },
   "validations":{
      "chars":{
         "code":"006",
         "message":"IBAN does not contain illegal characters"
      },
      "account":{
         "code":"002",
         "message":"Account Number check digit is correct"
      },
      "iban":{
         "code":"001",
         "message":"IBAN Check digit is correct"
      },
      "structure":{
         "code":"005",
         "message":"IBAN structure is correct"
      },
      "length":{
         "code":"003",
         "message":"IBAN Length is correct"
      },
      "country_support":{
         "code":"007",
         "message":"Country supports IBAN standard"
      }
   },
   "errors":[
      
   ]
}


5. API V4 Status Codes

Mathematical check digit and formatting validations are returned in the "validations" object
In the v4 version of the API we have separated each validation into its own object to make it easier access to each specific validation in your code.
This essentially means that instead of looping through the 'validations' object, you can simply reference the specific validation object by its name such as $validations->structure;

Status Code Type Description
301 Account Error API Key is invalid
302 Account Error Subscription expired
303 Account Error No queries available
304 Account Error You have no access to this API
305 Account Error IP Address not allowed
201 Validation Failed Account Number check digit not correct
202 Validation Failed IBAN Check digit not correct
203 Validation Failed IBAN Length is not correct
205 Validation Failed IBAN structure is not correct
206 Validation Failed IBAN contains illegal characters
207 Validation Failed Country does not support IBAN standard
001 Validation Success IBAN Check digit is correct
002 Validation Success Account Number check digit is correct
003 Validation Success IBAN Length is correct
004 Validation Success Account Number check digit is not performed for this bank or branch
005 Validation Success IBAN structure is correct
006 Validation Success IBAN does not contain illegal characters
007 Validation Success Country supports IBAN standard

6. Supported Countries

In this section you can find the list of supported countries by the IBAN Validation V4 API.
The Account Check column specifies if our service performs the secondary check digit validation of the account number inside the IBAN.

Country Code SEPA Length Account Check Branch IBAN Example
Albania AL No 28 AL35202111090000000001234567
Andorra AD Yes 24 AD1400080001001234567890
Austria AT Yes 20 AT483200000012345864
Azerbaijan AZ No 28 AZ77VTBA00000000001234567890
Bahrain BH No 22 BH02CITI00001077181611
Belgium BE Yes 16 BE71096123456769
Bosnia and Herzegovina BA No 20 BA393385804800211234
Brazil BR No 29 BR1500000000000010932840814P2
Bulgaria BG Yes 22 BG18RZBB91550123456789
Costa Rica CR No 22 CR23015108410026012345
Croatia HR Yes 21 HR1723600001101234565
Cyprus CY Yes 28 CY21002001950000357001234567
Czech Republic CZ Yes 24 CZ5508000000001234567899
Faroe Islands FO No 18 FO9264600123456789
Greenland GL No 18 GL8964710123456789
Denmark DK Yes 18 DK9520000123456789
Dominican Republic DO No 28 DO22ACAU00000000000123456789
Estonia EE Yes 20 EE471000001020145685
Egypt EG No 29 EG800002000156789012345180002
Finland FI Yes 18 FI1410093000123458
France FR Yes 27 FR7630006000011234567890189
Georgia GE No 22 GE60NB0000000123456789
Germany DE Yes 22 DE75512108001245126199
Gibraltar GI Yes 23 GI56XAPO000001234567890
Greece GR Yes 27 GR9608100010000001234567890
Guatemala GT No 28 GT20AGRO00000000001234567890
Hungary HU Yes 28 HU93116000060000000012345676
Iceland IS Yes 26 IS750001121234563108962099
Ireland IE Yes 22 IE64IRCE92050112345678
Israel IL No 23 IL170108000000012612345
Italy IT Yes 27 IT60X0542811101000000123456
Jordan JO No 30 JO71CBJO0000000000001234567890
Kazakhstan KZ No 20 KZ244350000012344567
Kosovo XK No 20 XK051212012345678906
Kuwait KW No 30 KW81CBKU0000000000001234560101
Latvia LV Yes 21 LV97HABA0012345678910
Lebanon LB No 28 LB92000700000000123123456123
Liechtenstein LI Yes 21 LI7408806123456789012
Lithuania LT Yes 20 LT601010012345678901
Luxembourg LU Yes 20 LU120010001234567891
North Macedonia MK No 19 MK07200002785123453
Malta MT Yes 31 MT31MALT01100000000000000000123
Mauritania MR No 27 MR1300020001010000123456753
Mauritius MU No 30 MU43BOMM0101123456789101000MUR
Moldova MD No 24 MD21EX000000000001234567
Monaco MC Yes 27 MC5810096180790123456789085
Montenegro ME No 22 ME25505000012345678951
Netherlands NL Yes 18 NL02ABNA0123456789
Norway NO Yes 15 NO8330001234567
Pakistan PK No 24 PK36SCBL0000001123456702
Palestine PS No 29 PS92PALS000000000400123456702
Poland PL Yes 28 PL10105000997603123456789123
Portugal PT Yes 25 PT50002700000001234567833
Qatar QA No 29 QA54QNBA000000000000693123456
Romania RO Yes 24 RO66BACX0000001234567890
San Marino SM Yes 27 SM76P0854009812123456789123
Saint Lucia LC No 32 LC14BOSL123456789012345678901234
Sao Tome and Principe ST No 25 ST23000200000289355710148
Saudi Arabia SA No 24 SA4420000001234567891234
Serbia RS No 22 RS35105008123123123173
Slovak Republic SK Yes 24 SK8975000000000012345671
Slovenia SI Yes 19 SI56192001234567892
Spain ES Yes 24 ES7921000813610123456789
Sweden SE Yes 24 SE7280000810340009783242
Switzerland CH Yes 21 CH5604835012345678009
Timor-Leste TL No 23 TL380010012345678910106
Tunisia TN No 24 TN5904018104004942712345
Turkey TR No 26 TR320010009999901234567890
United Arab Emirates AE No 23 AE460090000000123456789
United Kingdom GB Yes 22 GB33BUKB20201555555555
Holy See (the) VA Yes 22 VA59001123000012345678
Virgin Islands, British VG No 24 VG07ABVI0000000123456789
Ukraine UA No 29 UA903052992990004149123456789
Seychelles SC No 31 SC74MCBL01031234567890123456USD
Iraq IQ No 23 IQ20CBIQ861800101010500
Belarus BY No 28 BY86AKBB10100000002966000000
El Salvador SV No 28 SV43ACAT00000000000000123123
Libya LY No 25 LY38021001000000123456789
Sudan SD No 18 SD8811123456789012
Burundi BI No 27 BI43220001131012345678912345
Djibouti DJ No 27 DJ2110002010010409943020008
Russia RU No 33 RU0204452560040702810412345678901

FR includes:

  • French Guyana (GF)
  • Guadeloupe (GP)
  • Martinique (MQ)
  • Reunion (RE)
  • French Polynesia (PF)
  • French Southern Territories (TF)
  • Mayotte (YT)
  • New Caledonia (NC)
  • Saint Barthelemy (BL)
  • Saint Martin (French part) (MF)
  • Saint Pierre et Miquelon (PM)
  • Wallis and Futuna Islands (WF)

GB includes:

  • Isle of Man (IM)
  • Guernsey (GG)
  • Jersey (JE)
  • Channel Islands

FI includes:

  • Aland Islands (AX)

PT includes:

  • Azores and Madeira

ES includes:

  • Canary Islands (IC)
  • Ceuta and Melilla (EA)