IBAN validācijas API V4 dokumentācija

Šī API veido daļu no mūsu pakalpojuma IBAN komplekts

1. Kas jauns IBAN validācijas API V4?


Mēs pastāvīgi strādājam, lai uzlabotu mūsu pakalpojumus un nodrošinātu vēl labākus maksājumu validācijas risinājumus.
Iespējams, esat ievērojuši, ka IBAN komplekta API iterācija no V2 uz V4 ir izlaista.
Tas tika darīts, jo mēs apvienojām atsevišķas API, piemēram, SortWare v3, vienā versijas iterācijā, piem., v4.

Izmaiņu žurnāls (no v2 uz v4):


Pievienota jauna validācija (kļūda 206 un veiksmīgas izpildes paziņojums 006) – V4 API tagad pārbauda, vai IBAN ievade nesatur neatļautas rakstzīmes
Jaunais kļūdas kods – 206 (Validācija neizdevās) – ir saistīts ar šādu paziņojumu: IBAN satur neatļautas rakstzīmes.
Veiksmīgas izpildes paziņojuma kods šai pārbaudei ir 006 (Validācija veiksmīga), kuru papildina šāds paziņojums: IBAN nesatur neatļautas rakstzīmes.
Minētais kļūdas kods jums sniegs vairāk informācijas gadījumos, kad tiek iesniegti nevēlamus simbolus saturoši IBAN.
Agrāk šādā gadījumā darba režīms bija atbrīvoties no visiem nevēlamajiem simboliem un vienkārši turpināt validāciju.

Pievienota jauna validācija (kļūda 207 un veiksmīgas izpildes paziņojums 007) - Valsts neatbalsta IBAN
Šis validācijas slānis ļauj saņemt paziņojumu gadījumā, ja ievadītā IBAN valsts kods nav atrodams oficiālajā IBAN maksājumus atbalstošo valstu sarakstā.
Piemēram, izmantojot neuzticamu trešo pušu programmatūru, lietotājs var būt ģenerējis IBAN Amerikas Savienotajām Valstīm.
Tāds IBAN varētu izskatīties šādi: US64SVBKUS6S3300958879
Kā redzams, kontrolcipari ir pareizi, tādēļ attiecīgā pārbaude tiks izturēta, tomēr tas nav derīgs IBAN, jo Amerikas Savienotajās Valstīs IBAN banku maksājumiem neizmanto.


2. Funkcijas


IBAN validācijas API V4 ļauj izpildīt šādas darbības:

  • pārbaudīt IBAN derīgumu, izmantojot tā kontrolciparus;
  • pārbaudīt, vai IBAN satur derīgu vietējo bankas kontu un konta numura kontrolciparus *;
  • validēt IBAN garumu konkrētai valstij;
  • validēt IBAN struktūru/formātu konkrētai valstij;
  • validēt IBAN rakstzīmes (pārbaudīt, vai tas nesatur nederīgus simbolus);
  • validēt, vai valsts kods atbalsta IBAN standartu;

  • identificēt IBAN izdevējbanku;
  • identificēt IBAN izdevējvalsti un valsts kodu;
  • identificēt IBAN izdevējbankas adresi;
  • identificēt bankas BIC kodu;
  • identificēt bankas SEPA atbalstu: B2B, COR1, SCC, SCT, SDD.

* Bankas koda un konta numura validācija tiek veikta tikai noteiktām bankām un valstīm.

3. API V4 pieprasījumi



API sistēma ļauj automatizēt IBAN validāciju, izmantojot vienkāršu HTTP GET vai POST pieprasījumu.
Pieļaujamie parametri ir uzskaitīti zemāk redzamajā tabulā:

Lauka nosaukums Garums Veids Apraksts
IBAN Maks. 100 Virkne IBAN, kuru vēlaties validēt
api_key 128 Virkne Jūsu personīgā API atslēga
format 5 Virkne Atbildes formāts; tiek atbalstīts XML un JSON

*Lai iegūtu API atslēgu, lūdzu, sazinieties ar mums, rakstot uz e-pasta adresi contact@iban.com, vai iegādājieties abonementu mūsu pasūtījumu noformēšanas lapā

PIEMĒRS – IBAN validācija
Ja vēlaties, varat izmantot zemāk redzamo koda paraugu, lai pārbaudītu API darbību visizplatītākajās programmēšanas valodās.

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("\nPārbauda API - Sūtīt API POST pieprasījumu");
		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("\nSūta 'POST' pieprasījumu uz URL : " + url);
		System.out.println("Post parametri : " + urlParameters);
		System.out.println("Atbildes kods : " + 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("Lai turpinātu, nospiediet jebkuru taustiņu . . . ");
			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("Bankas nosaukums: " + data.bank_data.bank);
		console.log("Bankas BIC: " + data.bank_data.bic);
		console.log("Bankas pilsēta: " + data.bank_data.city);
		console.log("Bankas adrese: " + data.bank_data.address);
		console.log("Bankas pasta indekss: " + data.bank_data.zip);
		console.log("Bankas tālrunis: " + data.bank_data.phone);
		console.log("Bankas fakss: " + data.bank_data.fax);
		console.log("Bankas www: " + data.bank_data.www);
		console.log("Bankas e-pasts: " + data.bank_data.email);
		console.log("Bankas valsts nosaukums: " + data.bank_data.country);
		console.log("Bankas valsts kods: " + data.bank_data.country_iso);
		console.log("Iekšzemes konta numurs: " + data.bank_data.account);
		
    }
})


IBAN validācijas API lietojuma piemērs ar GET pieprasījumu apskatāms zemāk:

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

kur:
  • "key" ir jūsu API atslēga;
  • "IBAN", kas nosūtīts validācijai;
  • "xml" ir atbildes formāts; iespējams lietot arī atslēgvārdu "json", lai saņemtu atbildi json formātā.

Tiklīdz tiek veikts HTTP GET vai POST pieprasījums ar pareizo API atslēgu, sistēma atgriež rezultātus norādītajā formātā. Atbildes paraugs apskatāms nākamajā sadaļā "API atbildes struktūra".

4. API V4 atbilde

Zemāk atrodama API atbildes XSD shēma:




	 
		   
				 
					   
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
							 
							 
							 
							 
					   
				 
		   
		   
				 
					   
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
							 
								   
										 
											   
											   
										 
								   
							 
					   
				 
		   
		   
	 



Zemāk redzamajā tabulā dots detalizēts saņemto bank_data objekta lauku apraksts:

Lauka nosaukums Garums Veids Apraksts
BIC Maks. 11 Virkne Izdevējbankas/izdevējfiliāles vai izdevējiestādes BIC kods.
BANK Maks. 256 Virkne IBAN izdevējbankas/izdevējiestādes nosaukums.
BRANCH Maks. 256 Virkne Konkrētās bankas filiāles nosaukums, ja tāds ir pieejams.
COUNTRY Maks. 32 Virkne Pilns izcelsmes valsts nosaukums, piemēram, “United States”
COUNTRY_ISO 2 Virkne Divu burtu valsts koda saīsinājums, piem., LV, US, UK, FR… utt.
CITY Maks. 128 Virkne Izdevējbankas pilsētas nosaukums.
STATE Maks. 128 Virkne Štata nosaukums, kurā atrodas banka/filiāle.
ZIP Maks. 11 Virkne Pilsētas pasta indekss.
ADDRESS Maks. 128 Virkne Izdevējbankas adrese.
ACCOUNT Maks. 128 Virkne No IBAN iegūtais vietējais bankas konta numurs.
Zemāk redzamajā tabulā dots detalizēts saņemto sepa_data objekta lauku apraksts:

Lauka nosaukums Garums Tips Apraksts
SCT Maks. 3 Virkne Vai dotā banka atbalsta SEPA kredīta pārvedumu.
SDD Maks. 3 Virkne Vai dotā banka atbalsta SEPA tiešo debetu.
COR1 Maks. 3 Virkne Vai dotā banka atbalsta SEPA COR1.
B2B Maks. 3 Virkne Vai dotā banka atbalsta SEPA "Business to Business".
SCC Maks. 3 Virkne Vai dotā banka atbalsta SEPA karšu klīringu.


Zemāk dots piemērs XML atbildei no API uz IBAN validācijas vaicājumu:

	
		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 nesatur neatļautus simbolus 001 IBAN kontrolcipari ir pareizi 002 Konta numura kontrolcipari ir pareizi 005 IBAN struktūra ir pareiza 003 IBAN garums ir pareizs 007 Valsts atbalsta IBAN standartu

5. API V4 statusa kodi

Matemātisko kontrolciparu un formāta validācijas tiek atgrieztas "validations" objektā
API versijā V4 mēs katrai no validācijām esam iedalījuši atsevišķu objektu, lai jūsu kodā atvieglotu piekļuvi katrai konkrētai validācijai.
Tas būtībā nozīmē, ka tā vietā, lai cikliski izmantotu objektu "validations", jūs varat vienkārši atsaukties uz konkrēto validācijas objektu, norādot tā nosaukumu, piemēram, $validations->structure;

Statusa kods Veids Apraksts
301 Konta kļūda API atslēga nav derīga
302 Konta kļūda Beidzies abonements
303 Konta kļūda Vaicājumi nav pieejami
304 Konta kļūda Jums nav piekļuves šai API
305 Konta kļūda IP adrese nav atļauta
201 Validācija neizdevās Konta numura kontrolcipari nav pareizi
202 Validācija neizdevās IBAN kontrolcipari nav pareizi
203 Validācija neizdevās IBAN garums nav pareizs
205 Validācija neizdevās IBAN struktūra nav pareiza
206 Validācija neizdevās IBAN satur neatļautus simbolus
207 Validācija neizdevās Valsts neatbalsta IBAN standartu
001 Validācija veiksmīga IBAN kontrolcipari ir pareizi
002 Validācija veiksmīga Konta numura kontrolcipari ir pareizi
003 Validācija veiksmīga IBAN garums ir pareizs
004 Validācija veiksmīga Šai bankai vai filiālei netiek veikta konta numuru kontrolciparu pārbaude
005 Validācija veiksmīga IBAN struktūra ir pareiza
006 Validācija veiksmīga IBAN nesatur neatļautas rakstzīmes
007 Validācija veiksmīga Valsts atbalsta IBAN standartu