Dokumentacja API Walidacji IBAN V4

Niniejszy API jest częścią naszej usługi Pakietu IBAN

1. Co nowego w API Walidacji IBAN V4?


Nieustannie pracujemy nad ulepszaniem naszych usług oraz zapewnienianiem lepszych rozwiązań walidacji płatności.
Z pewnością zauważyliście, że API pakietu IBAN przeszło bezpośrednio z V2 do V4.
Stało się to w wyniku połączenia innych API, takich jak SortWare v3, w jedną wersjonowaną interację np. V4.

Changelog ( from v2 to v4 ):


Dodano nową walidację ( error 206 and success 006 ) - API V4 sprawdza obecność niedozwolonych znaków w podanym IBAN.
Nowy kod błędu - 206 (Validation Failed) z wiadomością: IBAN zawiera niedozwolone znaki.
Prawidłowy kod dla tej kontroli wynosi - 006 ( Validation Success ) z wiadomością: IBAN nie zawiera niedozwolonych znaków
Ten kod błędu udzieli ci więcej informacji w wypadku, gdy wprowadziłeś IBAN do naszego systemu bez alfa-numerycznych znaków.
Poprzednie działanie miało na celu usunięcie wszystkich znaków nie-alfa-numerycznych i przeprowadzenie walidacji

Dodano nową walidację ( error 207 and success 007 ) - Kraj nie wspiera IBAN
Niniejsza warstwa walidacji ujawni czy kod kraju podanego IBAN nie jest częścią oficjalnych krajów wspierających płatności IBAN.
Na przykład, użytkownik może wygenerować IBAN dla Stanów Zjedoczonych korzystając z niepewnwego oprogramowania stron trzecich
Taki IBAN może wyglądać jak następujący przykład US64SVBKUS6S3300958879
Zauważysz, że cyfra kontrolna jest poprawna i przejdzie walidacje modułu, jednakże nie jest to poprawny IBAN, ponieważ Stany Zjednoczone nie korzystają z IBAN przy płatnościach bankowych.


2. Funkcje


API Walidacji IBAN pozwala ci na następujące działania :

  • Walidację czy IBAN jest poprawny za pomocą ’ cyfr kontrolnych
  • Walidację czy IBAN ma poprawny krajowy kod banku i cyfry kontrolne numeru konta *
  • Walidację długości IBAN dla określonego kraju
  • Walidację struktury/formatowania IBAN dla określonego kraju
  • Walidację znaków IBAN ( sprawdza czy zawiera znaki nie-alfa-numeryczne )
  • Walidację czy dany kraj wspiera standard IBAN

  • Identyfikację banku, który wydał IBAN
  • Identyfikację kraju oraz kodu kraju danego IBAN
  • Identyfikację adresu banku, który wydał IBAN
  • Identyfikację kodu BIC banku’s
  • Identyfikację wsparcia SEPA przez bank’s: B2B,COR1,SCC,SCT,SDD

* Walidacje Kodu Banku oraz Numeru Konta są wykonywane tylko dla odpowiednich banków i krajów.

3. API V4 Requests



System API pozwala ci zautomatyzować walidację IBAN poprzez proste zapytania HTTP GET lub POST.
Akceptowane parametry zostały wymienione w tabelce poniżej:

Nazwa pola Długość Typ Opis
IBAN Maks. 100 Ciąg Znaków IBAN, który chcesz zwalidować.
api_key 128 Ciąg Znaków Twój osobisty klucz API.
format 5 Ciąg Znaków Obługiwane formaty odpowiedzi XML oraz JSON.

*Aby uzyskać klucz API skontaktuj się z nami pisząc na adres contact@iban.com lub wykup subskrypcję na naszej stronie zamówień

EXAMPLE – Zwaliduj IBAN
Możesz dowolnie korzystać z poniższej próbki kodu w celu przetestowania API w najpopularniejszych językach programowania..

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


Przykładowe użycie API walidacji IBAN z zapytaniem GET może zostać znalezione poniżej::

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

Gdzie:
  • Klucz jest twoim kluczem API
  • Moduł API wysyła IBAN do walidacji.
  • xml to format odpowiedzi. Słowo kluczowe json może zostać określone dla sformatowanej odpowiedzi json.

Gdy zapytanie HTTP GET lub POST zostanie wykonane z poprawnym kluczem API, system zwróci wyniki w określonym formacie. You can find an sample response in the next section “API Response Structure” Możesz znaleźć próbną odpowiedź w następnej sekcji Struktury” Odpowiedzi “API

4. Odpowiedź API V4

Schemat XSD odpowiedzi API’s może zostać znaleziony poniżej:




	 
		   
				 
					   
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
					   
				 
		   
		   
	 



A detailed description of the bank_data object fields returned can be seen in the table below:

Szczegółowy opis zwróconych pól obiektu bank_data można zobaczyć w tabelce poniżej
Nazwa Pola Długość Typ Opis
BIC Maks. 11 Ciąg znaków Kod BIC wydającego banku/oddziału lub instytucji.
BANK Maks. 256 Ciąg Znaków Nazwa banku/instytucji, które wydały IBAN
ODDZIAŁ Maks 256 Ciąg Znaków Nazwa określonego oddziału banku jest dostępna
KRAJ Maks. 32 Ciąg Znaków Pełna nazwa kraju pochodzenia np. “Stany Zjednoczone”
COUNTRY_ISO 2 Ciąg Znaków Dwuliterowy skrót kodu kraju np. US, UK, AU, FR … itp.
MIASTO Maks. 128 Ciąg Znaków Nazwa miasta, lokalizacja wydającego banku’s.
STAN Maks. 128 Ciąg Znaków Nazwa stanu, w którym bank/branch jest zlokalizowany.
KOD ZIP Maks. 11 Ciąg Znaków Kod pocztowy lub Zip miasta.
ADRES Maks 128 Ciąg Znaków Adres wydającego banku.
KONTO Maks. 128 Ciąg Znaków Numer konta banku krajowego pozyskany z IBAN.
Szczegółowy opis zwróconych pól obiektu sepa_data można zobaczyć w tabelce poniżej:

Nazwa Pola Długość Typ Opis
SCT Maks. 3 Ciąg Znaków Czy dany bank wspiera SEPA Credit Transfers.
SDD Maks. 3 Ciąg Znaków Czy dany bank wspiera SEPA Direct Debit.
COR1 Maks. 3 Ciąg Znaków Czy dany bank wspiera SEPA COR1.
B2B Maks. 3 Ciąg Znaków Czy dany bank wspiera SEPA Business to Business.
SCC Maks. 3 Ciąg Znaków Czy dany bank wspiera SEPA Card Clearing.


Przykładowa odpowiedź XML od API na walidację IBAN mogła by wyglądać tak:

	
		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 nie zawiera niedozwolonych znaków 001 Cyfra kontrolna IBAN jest poprawna 002 Cyfra kontrolna Numeru Konta jest poprawna 005 Struktura IBAN jest poprawna 003 Długość IBAN jest poprawna 007 Kraj wspiera standard IBAN

5. Kod statusu API V4

Matematyczne cyfry kontrolne oraz formatujące walidacje są zwracane w obiekcie "walidacje"
W wersji v4 API podzieliliśmy każdą walidację na swój własny obiekt, tak by ułatwić dostęp do każdej określonej walidacji w twoim kodzie.
To dosłownie oznacza, że zamiast przeglądać obiekt 'walidacji', możesz odnieść się do określonego obiektu walidacji po jego nazwie takiej jak $walidacje->struktura;

Kod Statusu Typ Opis
301 Błąd Konta Klucz API jest niepoprawny
302 Błąd Konta Subskrypcja Wygasła
303 Bląd Konta Brak dostępnych zapytań
304 Błąd Konta Nie masz dostępu do tego API
305 Błąd Konta IP Adres niedozwolony
201 Walidacja nie powiodła się Nieprawidłowa cyfra kontrolna numeru konta
202 Walidacja nie powiodła się Nieprawidłowa cyfra kontrolna IBAN
203 Walidacja nie powiodła się Nieprawidłowa długość IBAN
205 Walidacja nie powiodła się Nieprawidłowa Struktura IBAN
206 Walidacja nie powiodła się IBAN zawiera niedozwolone znaki
207 Walidacja nie powiodła się Kraj nie wspiera standardu IBAN
001 Walidacja Przebiegła Pomyślnie Cyfra Kontrolna IBAN jest poprawna
002 Walidacja Przebiegła Pomyślnie Cyfra kontrolna numeru konta jest poprawna
003 Walidacja Przebiegła Pomyślnie Długość IBAN jest poprawna
004 Walidacja Przebiegła Pomyślnie Cyfra kontrolna Numeru Konta nie jest wykonywana dla danego banku lub oddziału
005 Walidacja Przebiegła Pomyślnie Struktura IBAN jest poprawna
006 Walidacja Przebiegła Pomyślnie IBAN nie zawiera niedozwolonych znaków
007 Walidacja Przebiegła Pomyślnie Kraj wspiera standard IBAN