Dokumentace ověřování API IBAN

Toto rozhraní API je součástí naší IBAN Suite služby

1. Co je nového ve validačním API V4 IBAN?


Neustále pracujeme na zlepšování našich služeb a poskytování lepších řešení pro validaci plateb.
Možná jste si všimli, že IBAN Suite API přeskočila iteraci verze z V2 na V4.
Je to tak, protože jsme sjednotili jiné API jako SortWare v3 do jediné iterace verzování např. v4.

Změna (z v2 do v4 ):


Přidána nová validace (chyba 206 a úspěšnost 006) - API V4 nyní kontroluje, zda se ve vstupním IBANu nenachází ilegální znaky.
Nový chybový kód - 206 (Validace selhala) se zprávou: IBAN obsahuje neplatné znaky.
Úspěšný kód pro tuto kontrolu je - 006 (Validace byla úspěšná) se zprávou: IBAN neobsahuje ilegální znaky
Tento chybový kód vám poskytne více informací v případě, že do našeho systému odešlete IBAN s nealfanumerickými znaky.
Předchozí chování bylo odstranění všech nealfanumerických znaků a provedení ověření

Přidána nová validace (chyba 207 a úspěch 007) - Země nepodporuje IBAN
Tato validační vrstva bude oznamovat, zda kód země odeslaného IBAN není součástí oficiálních zemí podporujících platby IBAN.
Osoba může například vygenerovat IBAN pro Spojené státy pomocí softwaru nespolehlivé třetí strany
Takový IBAN může vypadat například US64SVBKUS6S3300958879
Všimnete si, že kontrolní číslice je správná a projde validací modulu, ale není to platný IBAN, protože Spojené státy nepoužívají IBAN pro bankovní platby.


2. Vlastnosti


Aplikaci IBAN Validace API V4 umožňuje provádět následující akce:

  • Ověřit, zda je IBAN platný pomocí kontrolních číslic
  • Ověřit, zda má IBAN platný kód domácí banky a kontrolní číslo účtu *
  • Ověřit délku IBAN pro konkrétní zemi
  • Ověřit strukturu / formátování IBAN pro konkrétní zemi
  • Ověřit znaky IBAN (kontrola nealfanumerických znaků)
  • Ověřit, zda kód země podporuje standard IBAN

  • Identifikovat banku, která IBAN vydala
  • Identifikovat zemi a kód země IBAN
  • Identifikovat adresu bank která vydala IBAN
  • Identifikovat banky ’s BIC kód
  • Identifikovat banky ’s SEPA podporu: B2B,COR1,SCC,SCT,SDD

* U některých bank a zemí se provádějí ověření bankovního kódu a ověření čísla účtu.

3. Požadavky API V4



Systém API umožňuje automatizovat ověření IBAN prostřednictvím jednoduchého požadavku HTTP GET nebo POST.
Přijaté parametry jsou uvedeny v následující tabulce:

Název pole Délka Typ Popis
IBAN Maximálně 100 Řetězec IBAN, který chcete ověřit.
api_key 128 Řetězec Váš osobní API klíč.
format 5 Řetězec Formát odpovědi XML a JSON podporován.

* Chcete-li získat klíč API, kontaktujte nás na adrese contact@iban.com nebo si zakoupte předplatné na naší objednávací stránce

EXAMPLE – Validate an IBAN
Pro testování rozhraní API v nejběžnějších programovacích jazycích můžete použít níže uvedený ukázkový kód.

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


Příklad použití API ověřování IBAN s požadavkem GET naleznete níže:

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

Kde:
  • klíč je váš API klíč
  • BAN odeslaný k ověření modulem API.
  • xml je formát odpovědi. Pro odpověď ve formátu json lze zadat také klíčové slovo json.

Jakmile je požadavek HTTP GET nebo POST proveden se správným klíčem API, systém vrátí výsledky v zadaném formátu. Ukázkovou odpověď naleznete v následující části “Struktura odpovědi API”

4. Odpověď API V4

Schéma XSD API ’s odpověď lze nalézt níže:




	 
		   
				 
					   
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
					   
				 
		   
		   
	 



Podrobný popis vrácených objektů bank_data lze zobrazit v následující tabulce:

Název pole Délka Typ Popis
BIC Maximálně 11 Řetězec Kód BIC vydávající banky / pobočky nebo instituce.
BANKA Maximálně 256 Řetězec Název banky / instituce, která IBAN vydala
POBOČKA Maximálně 256 řetězec Název konkrétní pobočky banky, je-li k dispozici
ZEMĚ Maximálně 32 Řetězec Úplný název země původu, např.“Spojené státy”
ZEMĚ_ISO 2 Řetězec Zkratka dvou písmen kódu země, např. US, UK, AU, FR… atd.
MĚSTO Maximálně 128 Řetězec Název města vydávající banky ’ umístění.
STÁT Maximálně 128 Řetězec Název státu, ve kterém se nachází banka / pobočka.
PSČ Maximálně 11 Řetězec PSČ města.
ADRESA Maximálně 128 Řetězec Adresa vystavující banky.
ÚČET Maximálně 128 Řetězec Číslo domácího bankovního účtu extrahované z IBAN.
Podrobný popis vrácených objektů sepa_data lze vidět v tabulce níže:

Název pole Délka Typ Popis
SCT Maximálně 3 Řetězec Zda tato banka podporuje SEPA Credit Transfer.
SDD Maximálně 3 Řetězec Zda tato banka podporuje SEPA inkaso.
COR1 Maximálně 3 Řetězec Zda tato banka podporuje SEPA COR1.
B2B Maximálně 3 Řetězec Zda tato banka podporuje SEPA Business to Business.
SCC Maximálně 3 Řetězec Zda tato banka podporuje zúčtování SEPA karty.


Vzorová odpověď XML z API pro dotaz na ověření IBAN by byla:

	
		BARCGB22
		INTERNATIONAL BANKING 2
		BARCLAYS BANK UK PLC
		
PO Box 69999 1 Churchill Place Canary Wharf
Londýn E14 1QE 020 71147000 GB 73160944
ANO ANO ANO ANO NE 006 IBAN neobsahuje neplatné znaky 001 Kontrola IBAN číslic je správná 002 Kontrolní číslo účtu je správné 005 Struktura IBAN je správná 003 Délka IBAN je správná 007 Země podporuje standard IBAN

5. Stavové kódy API V4

Matematická kontrolní číslice a validace formátování jsou vráceny v objektu "validace"
Ve verzi API rozhraní v4 jsme oddělili každou validaci na její vlastní objekt, což usnadňuje přístup ke každému konkrétnímu ověření v kódu.
To v podstatě znamená, že namísto smyčkování přes objekt „ověřování“ můžete jednoduše odkazovat na konkrétní objekt ověření jeho jména, jako je například $validations->structure;

Stavové kódy Typ Popis
301 Chyba účtu API klíč je neplatný
302 Chyba účtu Platnost předplatného vypršela
303 Chyba účtu Nejsou k dispozici žádné dotazy
304 Chyba účtu K tomuto rozhraní API nemáte přístup
305 Chyba účtu IP adresa není povolena
201 Validace selhala Kontrolní číslo účtu není správné
202 Validace selhala Kontrola IBAN číslic není správná
203 Validace selhala Délka IBAN není správná
205 Validace selhala Struktura IBAN není správná
206 Validace selhala IBAN obsahuje neplatné znaky
207 Validace selhala Země nepodporuje IBAN standard
001 Validace byla úspěšná Kontola IBAN číslic je správná
002 Validace byla úspěšná Kontrolní číslo účtu je správné
003 Validace byla úspěšná Délka IBAN je správná
004 Validace byla úspěšná Kontrolní číslo účtu nefunguje pro tuto banku nebo pobočku
005 Validace byla úspěšná Struktura IBAN je správná
006 Validace byla úspěšná IBAN neobsahuje neplatné znaky
007 Validace byla úspěšná Země podporuje IBAN standard