Documentazione API V4 Validazione IBAN

Questa API fa parte del nostro servizio IBAN Suite

1. Cosa c'è di nuovo nell'API di convalida IBAN V4?


Lavoriamo costantemente per migliorare i nostri servizi e fornire migliori soluzioni di convalida dei pagamenti.
Potresti notare che l'API di IBAN Suite ha saltato un'iterazione della versione da V2 a V4.
Ciò è stato fatto perché abbiamo unito le altre API come SortWare v3 in un'unica iterazione di versioni, ad esempio v4.

Changelog (dalla v2 alla v4):


Aggiunta nuova convalida (errore 206) - L'API V4 verifica ora i caratteri non validi nell'IBAN di input.
Il nuovo codice di errore - 206 (Convalida non riuscita) con messaggio: L'IBAN contiene caratteri non validi.
Questo codice di errore ti fornirà maggiori informazioni nel caso in cui tu invii un IBAN con caratteri non alfanumerici al nostro sistema.
Il comportamento precedente consisteva nel rimuovere tutti i caratteri non alfanumerici ed eseguire la convalida

Aggiunta nuova convalida (errore 207) - Il Paese non supporta IBAN
Questo livello di convalida segnalerà se il codice paese dell'IBAN presentato non fa parte dei paesi ufficiali che sostengono i pagamenti IBAN.
Ad esempio, una persona può generare un IBAN per gli Stati Uniti utilizzando un software di terze parti inaffidabile
Tale IBAN potrebbe assomigliare a US64SVBKUS6S3300958879
Si noterà che la cifra di controllo è corretta e passerà le convalide del modulo, tuttavia non è un IBAN valido poiché gli Stati Uniti non utilizzano l'IBAN per i pagamenti bancari.


2. Caratteristiche


L'API di convalida IBAN V4 consente di effettuare le seguenti operazioni:

  • Convalida se un IBAN è valido utilizzando le sue cifre di controllo
  • Convalida se un IBAN ha un codice bancario nazionale valido e cifre di controllo del numero di conto *
  • Convalidare la lunghezza dell'IBAN per un paese specifico
  • Convalidare la struttura/la formattazione IBAN per un paese specifico
  • Convalidare i caratteri IBAN (controllare caratteri non alfanumerici)
  • Convalidare se il codice paese supporta lo standard IBAN

  • Identificare la banca che ha emesso l'IBAN
  • Identificare il codice paese e paese di un IBAN
  • Identificare l'indirizzo della banca che ha emesso l'IBAN
  • Identificare il codice BIC della banca
  • Identificare il supporto SEPA della banca: B2B, COR1, SCC, SCT, SDD

* Le convalide del codice bancario e del numero di conto vengono eseguite solo per determinate banche e paesi.

3. Richieste API V2



Il sistema API consente di automatizzare la convalida IBAN tramite una semplice richiesta HTTP GET o POST.
I parametri accettati sono elencati nella tabella seguente:

Nome del campo Lunghezza Tipo Descrizione
IBAN Max 100 Stringa L'IBAN che vuoi convalidare.
api_key 128 Stringa La tua chiave API personale.
format 5 Stringa Formato della risposta XML e JSON supportati.

* Per ottenere una chiave API, ti preghiamo di contattarci all'indirizzo contact@iban.com o di acquistare un abbonamento nella nostra pagina degli ordini

ESEMPIO - Validazione di un IBAN
Sentiti libero di utilizzare il seguente codice di esempio per testare l'API nei linguaggi di programmazione più comuni.

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


Di seguito è riportato un utilizzo di esempio dell'API di convalida IBAN con una richiesta GET:

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

Dove:
  • la chiave è la tua chiave API
  • IBAN inviato per la convalida dal modulo API.
  • xml è il formato di risposta. È inoltre possibile specificare una parola chiave json per la risposta in formato json.

Una volta che una richiesta HTTP GET o POST viene eseguita con la chiave API corretta, il sistema restituirà i risultati nel formato specificato. Puoi trovare una risposta di esempio nella prossima sezione "Struttura delle risposte API"

4. Risposta API V2

Di seguito è riportato uno schema XSD della risposta dell'API:



	 
		   
				 
					   
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
					   
				 
		   
		   
	 




Una descrizione dettagliata dei campi oggetto bank_data restituiti può essere vista nella tabella seguente:

Nome del campo Lunghezza Tipo Descrizione
BIC Max 11 Stringa BIC - Il codice BIC della banca/filiale o istituzione emittente.
BANK Max 256 Stringa Il nome della banca/istituzione che ha emesso l'IBAN
BRANCH Max 256 Stringa Nome della filiale bancaria specifico se disponibile
COUNTRY Max 32 Stringa Nome completo del paese di origine, ad esempio "Stati Uniti"
COUNTRY_ISO 2 Stringa Abbreviazione di due lettere del codice del paese, ad esempio US, UK, AU, FR ecc.
CITY Max 128 Stringa Il nome della città della sede della banca emittente.
STATE Max 128 Stringa Stato - il nome dello stato in cui si trova la banca/filiale.
ZIP Max 11 Stringa CAP - CAP o codice postale della città.
ADDRESS Max 128 Stringa L'indirizzo bancario emittente.
ACCOUNT Max 128 Stringa Il numero di conto bancario nazionale estratto dall'IBAN.
Una descrizione dettagliata dei campi oggetto sepa_data restituiti può essere vista nella tabella seguente:

Nome del campo Lunghezza Tipo Descrizione
SCT Max 3 Stringa Se questa banca supporta il bonifico SEPA.
SDD Max 3 Stringa Se questa banca supporta l'addebito diretto SEPA.
COR1 Max 3 Stringa Se questa banca supporta SEPA COR1.
B2B Max 3 Stringa Se questa banca supporta SEPA Business to Business.
SCC Max 3 Stringa Se questa banca supporta la compensazione delle carte SEPA.


Una risposta XML di esempio dall'API per una query di convalida IBAN potrebbe essere:

	
		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 does not contain illegal characters 001 IBAN Check digit is correct 002 Account Number check digit is correct 005 IBAN structure is correct 003 IBAN Length is correct 007 Country supports IBAN standard

5. Codici di stato API V2

Le convalide delle cifre del controllo matematico vengono restituite nell'oggetto "validations"

Codice di stato Tipo Descrizione
301 Errore Account La chiave API non è valida
302 Errore Account Abbonamento scaduto
303 Errore Account Nessuna query disponibile
304 Errore Account Non hai accesso a questa API
201 Validazione Fallita La cifra di controllo del numero di conto non è corretta
202 Validazione Fallita La cifra di controllo IBAN non è corretta
203 Validazione Fallita La lunghezza dell'IBAN non è corretta
205 Validazione Fallita La struttura IBAN non è corretta
206 Validazione Fallita IBAN contiene caratteri illegali
207 Validazione Fallita Il Paese non supporta l'IBAN
001 Validazione eseguita con successo La cifra di controllo IBAN è corretta
002 Validazione eseguita con successo La cifra di controllo del numero di conto è corretta
003 Validazione eseguita con successo La lunghezza dell'IBAN è corretta
004 Validazione eseguita con successo Il numero di conto non supporta la cifra di controllo
005 Validazione eseguita con successo La struttura IBAN è corretta
006 Validazione eseguita con successo IBAN does not contain illegal characters
007 Validazione eseguita con successo Country supports IBAN standard