Документація по API V4 перевірки IBAN

Цей API є частиною нашогоКомплекту IBAN сервісу

1. Що нового у V4 API перевірки IBAN?


Ми постійно працюємо над вдосконаленням наших послуг і надаємо кращі рішення для перевірки платежів.
Можливо, ви помітили, що API Комплекту IBAN пропустив ітерацію версій від V2 до V4.
Це було зроблено, оскільки ми об'єднали інші API, такі як SortWare v3, в єдину ітерацію версій, наприклад, v4.

Журнал змін (від v2 до v4):


Додано нову перевірку (помилка 206 і успіх 006) - API V4 тепер перевіряє наявність неприпустимих символів у вхідному IBAN.
Новий код помилки - 206 (Не вдалося перевірити) з повідомленням: IBAN містить неприпустимі символи.
Код успішності цієї перевірки - 006 (успіх перевірки) з повідомленням: IBAN не містить нелегальних символів
Цей код помилки надасть вам додаткову інформацію, якщо ви надішлете IBAN з неалфавітно-цифровими символами до нашої системи.
Попередня поведінка полягала в тому, щоб позбутися всіх не алфавітно-цифрових символів і виконати перевірку

Додано нову перевірку (помилка 207 та успіх 007) - країна не підтримує IBAN
Цей рівень підтвердження буде повідомляти, якщо код країни наведеного IBAN не є частиною офіційних країн, що підтримують платежі IBAN.
Наприклад, людина може генерувати IBAN для Сполучених Штатів, використовуючи ненадійне програмне забезпечення третіх сторін
Такий IBAN може виглядати як US64SVBKUS6S3300958879
Ви помітите, що контрольна цифра є правильною і вона пройде перевірку модуля, однак це не є дійсним IBAN, оскільки США не використовують IBAN для банківських платежів.


2. Особливості


API перевірки IBAN V4 дозволяє виконувати наступне:

  • Перевіряти, чи діє IBAN, використовуючи цифри перевірки
  • Перевіряти, чи має IBAN дійсний код національного банку та номер перевірки номера рахунку *
  • Перевіряти довжину IBAN для конкретної країни
  • Перевіряти структуру / формат IBAN для конкретної країни
  • Перевіряти символи IBAN (перевірка на не буквено-цифрові символи)
  • Перевіряти, чи підтримує код країни стандарт IBAN

  • Визначате банк, який видав IBAN
  • Вказувати код країни та країни IBAN
  • Визначати адресу банку, що видав IBAN
  • Визначате BIC-код банку
  • Визначате підтримку SEPA банку: B2B,COR1,SCC,SCT,SDD

* Перевірка коду банку та номера рахунку здійснюється лише для певних банків і країн.

3. API V4 Запити



Система API дозволяє автоматизувати перевірку IBAN через простий запит HTTP GET або POST.
Допустимі параметри наведені в таблиці нижче:

Назва поля Довжина Тип Опис
IBAN Max 100 Рядок IBAN, який потрібно перевірити.
api_key 128 Рядок Ваш особистий ключ API.
формат 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

Where:
  • ключ - це ключ API
  • IBAN, надісланий для перевірки модулем API.
  • xml є форматом відповіді. Також може бути вказано ключове слово json для jss-форматованох відповіді.

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

4. API V4 Відповідь

Нижче наведено схему XSD відповіді API:




	 
		   
				 
					   
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
					   
				 
		   
		   
	 



Детальний опис повернених об'єктів bank_data можна побачити в таблиці нижче:

Назва поля Довжина Тип Опис
BIC Max 11 Рядок Код BIC банку / відділення чи установи емітента.
БАНК Max 256 Рядок Назва банку / установи, що видала IBAN
ВІДДІЛЕННЯ Max 256 Рядок Ім'я конкретного відділення банку, якщо воно доступне
КРАЇНА Max 32 Рядок Повна назва країни походження, наприклад, “Сполучені Штати”
КРАЇНА_ISO 2 Рядок Дві букви абревіатури коду країни напр. US, UK, AU, FR … тощо.
МІСТО Max 128 Рядок Назва міста банку-емітента.
ОБЛАСТЬ Max 128 Рядок Назва держави, в якій знаходиться банк / відділення.
ПОШТОВИЙ ІНДЕКС Max 11 Рядок Поштовий індекс міста.
АДРЕСА Max 128 Рядок Адреса банку-емітента.
РАХУНОК Max 128 Рядок Номер внутрішнього банківського рахунку, витягнутий з IBAN.
Детальний опис повернутих об'єктів sepa_data можна побачити в таблиці нижче:

Назва поля Довжина Тип Опис
SCT Max 3 Рядок Чи підтримує цей банк кредитний переказ SEPA.
SDD Max 3 Рядок Чи підтримує цей банк прямий дебет SEPA.
COR1 Max 3 Рядок Чи підтримує цей банк SEPA COR1.
B2B Max 3 Рядок Whether this bank supports SEPA B2B.
SCC Max 3 Рядок Чи підтримує цей банк очищення картки SEPA.


Зразок XML-відповіді з API для запиту перевірки IBAN буде:

	
		BARCGB22
		МІЖНАРОДНИЙ БАНКІНГ 2
		BARCLAYS BANK UK PLC
		
PO Box 69999 1 Churchill Place Canary Wharf
Лондон E14 1QE 020 71147000 GB 73160944
ТАК ТАК ТАК ТАК НІ 006 IBAN не містить заборонених символів 001 Контрольна цифра IBAN є правильною 002 Контрольний номер правильний 005 Структура IBAN правильна 003 Довжина IBAN є правильною 007 Країна підтримує стандарт IBAN

5.Коди статусу API V4

Математичні контрольні цифри і перевірки форматування повертаються в об'єкті "перевірки"
У v4 версії API ми розділили кожну перевірку на власний об'єкт, щоб полегшити доступ до кожної конкретної перевірки коду.
Це, по суті, означає, що замість циклічного перегляду об'єкта 'validations' можна просто посилатися на конкретний об'єкт перевірки за його назвою, наприклад $validations-> structure;

Код статусу Тип Опис
301 Помилка облікового запису Ключ API недійсний
302 Помилка облікового запису Термін дії підписки закінчився
303 Помилка облікового запису Немає доступних запитів
304 Помилка облікового запису Ви не маєте доступу до цього API
305 Помилка облікового запису IP-адреса не дозволена
201 Помилка перевірки Номер рахунку не перевірено
202 Помилка перевірки Контрольна цифра IBAN невірна
203 Помилка перевірки Довжина IBAN не правильна
205 Помилка перевірки Структура IBAN неправильна
206 Помилка перевірки IBAN містить нелегальні символи
207 Помилка перевірки Країна не підтримує стандарт IBAN
001 Успіх перевірки Контрольна цифра IBAN є правильною
002 Успіх перевірки Номер контрольного номера правильний
003 Успіх перевірки Довжина IBAN є правильною
004 Успіх перевірки Номер контрольного номера для цього банку або відділення не виконується
005 Успіх перевірки Структура IBAN правильна
006 Успіх перевірки IBAN не містить заборонених символів
007 Успіх перевірки Країна підтримує стандарт IBAN