IBAN-vahvistus API V4 -dokumentaatio

Tämä API on osa IBAN Suite -palveluamme

1. Mitä uutta V4 IBAN-vahvistus-API:ssa on?


Pyrimme jatkuvasti kehittämään palveluitamme sekä tarjoamaan parempia maksuvahvistusratkaisuja.
Olet saattanut huomata, että IBAN Suite -API on päivitetty versiosta V2 versioon V4.
Tämä johtuu siitä, että olemme yhdistäneet muita API:ja, kuten SortWare v3:n, versioon v4.

Muutosloki versiosta v2 versioon v4):


Lisätty uusi vahvistus (virhe 206 ja onnistunut 006) - V4 API tarkistaa nyt IBAN-numeron syötössä virheellisiä merkkejä.
Uusi virhekoodi - 206 (vahvistus epäonnistui) viestillä: IBAN sisältää virheellisiä merkkejä.
Tämän tarkistuksen onnistumista kuvaava koodi on - 006 (vahvistus onnistui) viestillä: IBAN ei sisällä virheellisiä merkkejä
Tämä virhekoodi tarjoaa lisätietoa, mikäli syötät järjestelmäämme IBAN-numeron, jossa on muita kuin alfanumeerisia merkkejä.
Edellisen toimen tarkoituksena on poistaa kaikki muut kuin alfanumeeriset merkit sekä suorittaa vahvistus

Lisätty uusi vahvistus (virhe 207 ja onnistunut 007) - Maa ei tue IBAN-numeroa
Tämä vahvistusvaihe ilmoittaa, jos syötetyn IBAN-numeron maakoodi ei ole osa IBAN-maksuja tukevia virallisia maita.
Yhdysvaltojen IBAN-numeron voi esimerkiksi muodostaa epäluotettavilla kolmansien osapuolten ohjelmistoilla
Tällainen IBAN-numero voi näyttää tältä: US64SVBKUS6S3300958879
Huomaat, että tarkistenumero on oikein ja se menee läpi moduulivahvistuksissa, mutta se ei kuitenkaan ole oikea IBAN, koska Yhdysvallat ei käytä pankkimaksuissa IBAN-numeroita.


2. Ominaisuudet


IBAN-vahvistus-API API V4 antaa sinulle mahdollisuuden seuraaviin:

  • Vahvistaa, onko IBAN-numerossa oikeat ’tarkistenumerot
  • Vahvistaa, onko IBAN-numerossa oikea pankkikoodi ja tilinumeron tarkistenumero*
  • Tarkistaa kyseisen maan IBAN-numeron pituuden
  • Tarkistaa kyseisen maan IBAN-numeron rakenteen/muodon
  • Tarkistaa IBAN-merkit (tarkistaa muut kuin alfanumeeriset merkit)
  • Tarkistaa, tukeeko maakoodi IBAN-standardia

  • Tunnistaa IBAN-numeron myöntäneen pankin
  • Tunnistaa IBAN-numeron maan ja maakoodin
  • Tunnistaa IBAN-numeron myöntäneen pankin osoitteen
  • Tunnistaa pankin’ BIC-koodin
  • Tunnistaa pankin’ SEPA-tuki: B2B,COR1,SCC,SCT,SDD

*Pankkikoodien ja tilinumeroiden vahvistukset suoritetaan vain tiettyjen pankkien ja maiden osalta.

3. API V4 -pyynnöt



API-järjestelmä antaa sinulle mahdollisuuden automoida IBAN-vahvistusta yksinkertaisten HTTP GET - tai POST -pyyntöjen avulla.
Hyväksytyt parametrit on listattu alla olevaan taulukkoon:

Kentän nimi Pituus Tyyppi Kuvaus
IBAN Maks. 100 Merkkijono Vahvistettava IBAN.
api_avain 128 Merkkijono Oma API-avaimesi.
muoto 5 Merkkijono XML- ja JSON-vasteiden tuetut muodot.

*Hanki API-avain ottamalla meihin yhteyttä osoitteeseen contact@iban.com tai tee tilaus tilaussivuillamme

ESIMERKKI – Vahvista IBAN
Voit käyttää alla olevaa mallikoodia testataksesi API:a yleisimmissä ohjelmointikielissä.

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


Voit löytää alta esimerkiin IBAN-vahvistus-API:n käytöstä GET-pyynnöllä:

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

Missä:
  • avain on API-avaimesi
  • API-moduulin lähettämä IBAN vahvistustarkoitukseen.
  • xml on vastausmuoto. Json-avainsana voidaan myös määrittää json-vasteeksi.

Kun HTTP GET - tai POST-pyyntö on oikealla API-avaimella, järjestelmä palauttaa tulokset tietyssä muodossa. Voit löytää mallivastauksen seuraavasta osiosta “API-vastauksen rakenne”

4. API V4 -vastaus

API-vastauksen XSD-malli löytyy alta:




	 
		   
				 
					   
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
					   
				 
		   
		   
	 



Alla olevassa taulukossa on yksityiskohtainen kuvaus palautuvista pankkitietokentistä:

Kentän nimi Pituus Tyyppi Kuvaus
BIC Maks. 11 Merkkijono Pankin/haarakonttorin tai instituution BIC-koodi.
PANKKI Maks. 256 Merkkijono IBAN-numeron myöntäneen pankin/instituution nimi
HAARAKONTTORI Maks. 256 Merkkijono Tietyn pankin haarakonttorin nimi
MAA Maks. 32 Merkkijono Alkuperämaan koko nimi, esim. “Yhdysvallat”
MAA_ISO 2 Merkkijono Maakoodin kaksikirjaiminen lyhenne, esim. US, UK, AU, FR … jne.
KAUPUNKI Maks. 128 Merkkijono Myöntäneen pankin kaupunki.
MAAKUNTA Maks. 128 Merkkijono Maakunta, jossa pankki/haarakonttori sijaitsee.
POSTINUMERO Maks. 11 Merkkijono Kaupungin postinumero.
OSOITE Maks. 128 Merkkijono Pankin osoite.
TILI Maks. 128 Merkkijono IBAN-numerosta poimittu tilinumero.
Alla olevassa taulukossa on yksityiskohtainen kuvaus palautuneista septa-tietokentistä:

Kentän nimi Pituus Tyyppi Kuvaus
SLS Maks. 3 Merkkijono Tukeeko tämä pankki SEPA-luottosiirtoa.
SPS Maks. 3 Merkkijono Tukeeko tämä pankki SEPA-pankkisiirtoa.
COR1 Maks. 3 Merkkijono Tukeeko tämä pankki SEPA COR1:a.
B2B Maks. 3 Merkkijono Tukeeko tämä pankki yritysten välistä SEPA-siirtoa.
SKS Maks. 3 Merkkijono Tukeeko tämä pankki SEPA-korttiselvitystä.


IBAn-vahvistuskyselyn API:n tuottama XML-mallivastaus olisi:

	
		BARCGB22
		KANSAINVÄLINEN PANKKI 2
		BARCLAYS BANK UK PLC
		
PO Box 69999 1 Churchill Place Canary Wharf
Lontoo E14 1QE 020 71147000 GB 73160944
KYLLÄ KYLLÄ KYLLÄ KYLLÄ EI 006 IBAN ei sisällä virheellisiä merkkejä 001 IBAN-tarkistenumero on oikein 002 Tilinumeron tarkistenumero on oikein 005 IBAN-numeron rakenne on oikein 003 IBAN-numeron pituus on oikein 007 Maa tukee IBAN-standardia

5. API V4 -tilakoodit

Matemaattinen tarkistenumero ja muotoilun vahvistukset palautetaan vahvistusobjektissa
Olemme erotelleet API:n v4-versiossa kunkin vahvistuksen omaan objektiinsa helpottaaksemme kunkin erillisen vahvistuksen tekemistä.
Tämä tarkoittaa, että sen sijaan, että sinun täytyisi hyppiä eri vahvistusobjektien välillä, voit vain viitata tiettyyn vahvistusobjektiin sen nimellä, kuten $vahvistukset->rakenne;

Tilakoodi Tyyppi Kuvaus
301 Tilivirhe API-avain on virheellinen
302 Tilivirhe Tilaus on päättynyt
303 Tilivirhe Kyselyjä ei ole saatavilla
304 Tilivirhe Sinulla ei ole käyttöoikeutta tähän API:n
305 Tilivirhe IP-osoite ei ole sallittu
201 Vahvistus epäonnistui Tilinumeron tarkistenumero on virheellinen
202 Vahvistus epäonnistui IBAN-numeron tarkistenumero on virheellinen
203 Vahvistus epäonnistui IBAN-numeron pituus on virheellinen
205 Vahvistus epäonnistui IBAN-numeron rakenne on virheellinen
206 Vahvistus epäonnistui IBAN sisältää virheellisiä merkkejä
207 Vahvistus epäonnistui Maa ei tue IBAN-standardia
001 Vahvistus onnistui IBAN-numeron tarkistenumero on oikein
002 Vahvistus onnistui Tilinumeron tarkistenumero on oikein
003 Vahvistus onnistui IBAN-numeron pituus on oikein
004 Vahvistus onnistui Tilinumeron tarkistenumero ei ole oikein tälle pankille tai haarakonttorille
005 Vahvistus onnistui IBAN-numeron rakenne on oikein
006 Vahvistus onnistui IBAN ei sisällä virheellisiä merkkejä
007 Vahvistus onnistui Maa tukee IBAN-standardia