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 V2 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.

*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 V2 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:

	
		BARCGB22
		INTERNATIONAL BANKING 2
		BARCLAYS BANK UK PLC
		
PO Box 69999 1 Churchill Place Canary Wharf
London E14 1QE 020 71147000 GB 73160944
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

5. API V2 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 it's 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 it's 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

If you are looking for the documentation for our legacy IBAN Validation API V2, you may find it at Legacy API V2 Documentation