Документация API для проверки IBAN, версия 4

Данный API является часть сервиса IBAN Suite

1. Что нового в 4 версии API для проверки IBAN?


Мы постоянноо работаем над повышением качества предоставляемых услуг и повышением надежности инструментов для проверки данных.
Возможно, вы обратили внимание, что за 2 версией IBAN Suite API последовала сразу 4 версия.
Это произошло из-за того, что мы объединили отдельные API, такие, как SortWare 3 версии в единую систему.

Журнал изменений (между 2 и 4 версиями):


Добавлена новая проверка (ошибка 206) - 4 версия интерфейса проверяет наличие недопустимых символов при вводе IBAN.
Новый код ошибки - 206 (Ошибка проверки) содержит следующее сообщение: IBAN contains illegal characters.
Данный код ошибки появляется только в том случае, когда вы используете недопустимые символы при указании IBAN-номера в нашей системе.
Ранее в системе использовался алгоритм, удаляющий любые запрещенные символы, после чего запускалась проверка.

Добавлена новая проверка ( error 207 ) - Страна не работает с IBAN
Данный элемент позволяет определить ситуацию, когда для выбранной страны отсутствует возможность расчета IBAN.
Например, пользователь создает IBAN для США, используя стороннее программное обеспечение
Такой IBAN может иметь следующий вид: US64SVBKUS6S3300958879
Вы отметить правильность номера, который пройдет все проверки, однако, данный номер нельзя использовать, потому что IBAN не доступен на территории США.


2. Основные функции


Интерфейс для проверки IBAN позволяет выполнять следующие задачи:

  • Проверка действительности IBAN-номера на основе содержащихся в нем символов
  • Провекра наличия внутреннего кода банка и номера счета*
  • Провекра длины IBAN для выбранной страны
  • Проверка структуры и формата IBAN для выбранной страны
  • Проверка символов в IBAN (наличие запрещенных символов)
  • Проверка возможности использования IBAN на территории выбранной страны

  • Определение банка, выпустившего данный IBAN
  • Определение страны и кода страны для IBAN
  • Определение адреса банка для заданного IBAN
  • Определение БИК банка
  • Определение наличие поддержки SEPA: B2B,COR1,SCC,SCT,SDD

* Проверка по коду банка и номеру счета производится только для определенных стран.

3. Запросы API V2



Система API позволяет автоматизировать процесс проверки IBAN, используя HTTP GET или POST запросы.
Допустимые параметры представлены в следующей таблице:

Название поля Длина Тип Описание
IBAN Макс. 100 Строка IBAN для проверки.
api_key 128 Строка Ваш личный API-ключ.
format 5 Строка Формат ответа в XML и JSON.

*Для получения API-ключа, пожалуйста, напишите на contact@iban.com или приобретите подписку на странице оформления заказа

ПРИМЕР – Проверка IBAN
Вы можете использовать приведенных ниже код для проверки API в одном из самых распространенных языков программирования.

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);
		
    }
})


Ниже представлен пример использования API для проверки IBAN с запросом GET:

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

Данные:
  • - ваш API-ключ
  • - IBAN, отправленный для проверки.
  • - формат xml для ответа. Кроме того, вы можете выбрать формат json.

После того, как запрос HTTP GET или POST отправлен с использованием правильного API-ключа, система предоставит ответ в указанном формате. Пример ответа системы вы сможете найти в следующем разделе: “Структура ответа API”

4. Структура ответа API

Схема XSD ответа API представлена ниже:


  
    
      
        
          
            
              
              
              
              
              
              
              
              
              
              
              
              
              
              
            
          
        
        
          
            
              
              
              
              
              
            
          
        
        
          
            
              
                
                  
                    
                    
                  
                
              
            
          
        
        
      
    
  

Подробная информация о каждом из полей ответа представлена в данной таблице:

Поле Длина Тип Описание
BIC Макс. 11 Строка БИК организации, создавшей данный IBAN.
BANK Макс. 256 Строка Наименование организации, создавшей данный IBAN
BRANCH Макс. 256 Строка Наименование отделения организации, создавшей данный IBAN
COUNTRY Макс. 32 Строка Полное наименование страны, например, США
COUNTRY_ISO 2 Строка Двухзначный код страны, например, US, UK, AU, FR … etc.
CITY Макс. 128 Строка Город организации, создавшей данный IBAN.
STATE Макс. 128 Строка Государство организации, создавшей данный IBAN.
ZIP Макс. 11 Строка Индекс организации, создавшей данный IBAN.
ADDRESS Макс. 128 Строка Адрес организации, создавшей данный IBAN.
ACCOUNT Макс. 128 Строка Внутренний номер счета, полученный из IBAN.
Подробное описание полей объекта sepa_data представлено в следующей таблице:

Поле Длина Тип Описание
SCT Макс. 3 Строка Поддержка безналичных расчетов SEPA данным банком.
SDD Макс. 3 Строка Поддержка прямого пополнения SEPA данным банком.
COR1 Макс. 3 Строка Поддердка SEPA COR1 данным банком.
B2B Макс. 3 Строка Поддержка SEPA Business to Business данным банком.
SCC Макс. 3 Строка Поддержка SEPA Card Clearing данным банком.


Ниже представлен пример XML-ответа от API-интерфейса при проверке IBAN:

	
		BARCGB22
		CHELTENHAM
		BARCLAYS BANK PLC
		
Leicester LE87 2BB 0345 7345345 United Kingdom GB 30093459
YES YES YES YES NO 002 Account Number check digit is correct 001 IBAN Check digit is correct 005 IBAN structure is correct 003 IBAN Length is correct

5. Коды состояния API V2

Результаты математической проверки представлены в объекте "validations"

Код состояния Тип Описание
301 Ошибка учетной записи Неправильный API-ключ
302 Ошибка учетной записи Истек срок действия подписка
303 Ошибка учетной записи Нет доступных запросов
304 Ошибка учетной записи У вас нет доступа к данному API
201 Ошибка проверки Ошибка проверки номера счета
202 Ошибка проверки Проверочные символы IBAN не совпадают
203 Ошибка проверки Неправильная длина IBAN
205 Ошибка проверки Неправильная структура IBAN
206 Ошибка проверки IBAN содержит запрещенные символы
207 Ошибка проверки Страна не поддерживает IBAN
001 Успешная проверка Корректные проверочные символы IBAN
002 Успешная проверка Корректный номер счета IBAN
003 Успешная проверка Правильная длина IBAN
004 Успешная проверка Номер счета не поддерживает проверочные символы
005 Успешная проверка Правильная структура IBAN

Если вам требуется документация к 2 версии API для проверки IBAN, вы можете скачать ее здесь Legacy API V2 Documentation