IBAN Validation API V4 Документация

Този API е част от нашата IBAN Suite услуга

1. Какво е новото в V4 API за валидиране на IBAN?


Ние непрекъснато работим за подобряване на нашите услуги и за осигуряване на по-добри решения за валидиране на плащанията.
Може да сте забелязали, че IBAN Suite API е пропуснал версия на версията от V2 на V4.
Това е направено, защото сме обединили другите API, като SortWare v3, в една итерация на версии, напр. v4.

Списък с промени (от v2 до v4):


Добавена е нова проверка (грешка 206 и успех 006) - V4 API сега проверява за непозволени знаци във входния 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 String IBAN, който искате да потвърдите.
api_key 128 String Вашият персонален API ключ.
format 5 String Поддържа се форматът на отговора 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, изпратен за проверка от модула на приложния програмен интерфейс (API).
  • xml е форматът за отговор. Също така може да бъде посочена и ключова дума json за json форматиран отговор.

След като HTTP GET или POST заявка е направена с правилния API ключ, системата ще върне резултатите в указания формат. Можете да намерите примерни отговори в следващия раздел “Структура на отговора на API”

4. Отговор на API V4

Схемата за отговор на XSD на API може да бъде намерена по-долу:




	 
		   
				 
					   
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
					   
				 
		   
		   
	 



Подробно описание на връщаните полета bank_data можете да видите в таблицата по-долу:

Име на полето Дължина Тип Описание
BIC Max 11 String Кодът BIC на банката-издател / клон или институция.
BANK Max 256 String Името на банката / институцията, издала IBAN
BRANCH Max 256 String Име на конкретния банков клон, ако има такъв
COUNTRY Max 32 String Пълно наименование на страната на произход, напр. “Съединените Щати”
COUNTRY_ISO 2 String Двубуквено съкращение на кода на страната напр. US, UK, AU, FR … и т.н..
CITY Max 128 String Името на града, където се намира банката-издател
STATE Max 128 String Името на държавата, в която се намира банката / клона.
ZIP Max 11 String Пощенски код или пощенски код на града.
ADDRESS Max 128 String Адресът на банката-издател.
ACCOUNT Max 128 String Номерът на вътрешната банкова сметка, извлечен от IBAN.
Подробно описание на връщаните полета sepa_data може да се види в таблицата по-долу:

Име на полето Дължина Тип Описание
SCT Max 3 String Дали тази банка поддържа кредитния превод на SEPA.
SDD Max 3 String Дали тази банка поддържа SEPA директен дебит.
COR1 Max 3 String Дали тази банка поддържа SEPA COR1.
B2B Max 3 String Дали тази банка поддържа SEPA Business to Business.
SCC Max 3 String Дали банката поддържа SEPA Card Clearing.


Примерен XML отговор от API за заявка за потвърждаване на IBAN ще бъде:

	
		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 не съдържа непозволени знаци 001 IBAN Контролната цифра е правилна 002 Контролната цифра на номера на сметката е правилна 005 IBAN структурата е правилна 003 Дължината на IBAN е правилна 007 Държавата поддържа IBAN стандарт

5. Кодове за състояние на API V4

Математическата контролна цифра и валидациите за форматиране се връщат в обекта "валидации"
В v4 версията на API сме разделили всяко валидиране в негов собствен обект, за да направим по-лесен достъпа до всяка конкретна проверка в кода.
Това по същество означава, че вместо да използвате цикъл за обекта "validations", можете просто да посочите конкретния обект за валидиране с неговото име, като например $validations->structure;

Статус Код Тип Описание
301 Account Error Ключът на API е невалиден
302 Account Error Абонаментът е изтекъл
303 Account Error Няма налични заявки
304 Account Error Нямате достъп до този приложен програмен интерфейс (API)
305 Account Error IP адресът не е разрешен
201 Validation Failed Номерът на профила за проверка не е правилен
202 Validation Failed IBAN Контролната цифра не е правилна
203 Validation Failed Дължината на IBAN не е правилна
205 Validation Failed IBAN структурата не е правилна
206 Validation Failed IBAN съдържа непозволени знаци
207 Validation Failed Държавата не поддържа IBAN стандарт
001 Validation Success IBAN Контролната цифра е правилна
002 Validation Success Проверката на номера на сметката е правилна
003 Validation Success Дължината на IBAN е правилна
004 Validation Success Проверка на номера на сметката не се извършва за тази банка или клон
005 Validation Success IBAN структурата е правилна
006 Validation Success IBAN не съдържа непозволени знаци
007 Validation Success Държавата поддържа IBAN стандарт