IBAN Calculatie API Documentatie



API integratie dienst


1. Wat is de IBAN Calculatie API?


De IBAN Calculatie (AKA IBAN Conversie) engine is een software systeem waarmee onze klanten binnenlandse rekeningnummers kunnen omzetten naar International Bank Account Numbers (IBAN).

Het systeem is voor onze klanten zowel via de manual interface als met een API beschikbaar.

Het systeem kan ook de bank of financiële instelling van een rekeningnummer weergeven.



2. Functies


Onderstaand enkele hoofdfuncties van onze IBAN Calculatie engine:




3. Ondersteunde Landen


De IBAN Calculatie API werkt momenteel met de onderstaande landen.

Landcode Landnaam Bankcode Afdeling Rekening Controlecijfer
AT Oostenrijk YES   YES  
BE België YES   YES YES
CH Zwitserland YES   YES  
DE Duitsland YES   YES  
EE Estland     YES  
ES Spanje YES YES YES YES
FI Finland     YES YES
FR Frankrijk YES YES YES YES
GB Verenigd Koninkrijk YES   YES YES
HU Hongarije     YES YES
IE Ierland YES   YES YES
IT Italië YES YES YES YES
MC Monaco YES YES YES YES
MR Mauritanië YES YES YES  
MT Malta YES   YES  
NO Noorwegen     YES YES
PT Portugal YES YES YES YES
SE Zweden YES   YES  
SM San Marino YES YES YES  
CZ Tsjechië YES   YES YES
AL Albanië YES   YES  
SK Slowakije YES   YES YES
SI Slovenië YES   YES YES
PL Polen YES   YES YES
SE Zweden YES   YES YES
NL Netherlandds YES YES
Enkel als de controlecijfer-kolom ingevuld is, ondersteunt het land deze controle.

De controlecijfer-validatie is een extra beveiligingslaag tegen typefouten.



4. API Inputs


De API accepteert zowel HTTP GET als POST request voor de invoer van data.
De gevraagde parameters staan in onderstaande tabel:

Veldnaam Type Beschrijving
api_key String Persoonlijke API-sleutel.
format String API response formaat (XML of JSON)
country String Landcode (UK/US/DE/FR/...)
bankcode String Unieke bankcode
branch String Unieke lokale takcode (optioneel)
account String Rekeningnummer
cd Integer Controlecijfers gebruikt in bepaalde landen
prefix Integer Enkel nodig voor Tsjechië
De eerste parameter is de API-sleutel, dit is een unieke string die ons systeem toestaat de gebruiker te identificeren.

De API ondersteunt meerdere response formaten om integratie makkelijker te maken. Momenteel zijn XML en JSON ondersteund.

De landparameter moet bestaan uit een 2-cijferige ISO code, bijvoorbeeld UK voor het Verenigd Koninkrijk, DE voor Duitsland, ...
Bankcode heeft een verschillende lengte en structuur voor elk land.

Takcode is een optionele parameter enkel nodig voor sommige landen.
Rekeningnummer is nodig voor alle landen, in sommige gevallen is dit zelf de enige verplichte parameter om een IBAN te berekenen.

Het controlecijfer is enkel verplicht voor bepaalde landen die deze gebruiken. Zie de voorbeelden.

Prefix is een veld enkel nodig om een IBAN voor Tsjechië te berekenen.



5. API Voorbeelden


In onderstaande tabel kan je een werkend voorbeeld vinden van een GET-query naar onze API voor elk land.

Land Voorbeeld query (GET REQUEST)
AT ?country=AT&format=json&bankcode=12000&account=52700357958
BE ?country=BE&format=json&bankcode=250&account=0135106&cd=70
CH ?country=CH&format=json&bankcode=0240&account=240C08011570
DE ?country=DE&format=json&bankcode=BLZ37010050&account=399509
EE ?country=EE&format=json&account=55000005511439
ES ?country=ES&format=json&bankcode=0081&branch=1731&cd=91&account=0006040912
FI ?country=FI&format=json&account=52900261901092
FR ?country=FR&format=json&bankcode=30056&branch=00264&account=02640016443
GB ?country=GB&format=json&bankcode=090127&account=93496333
HU ?country=HU&format=json&account=107000240416330551100005
IE ?country=IE&format=json&bankcode=905838&account=71924374
IT ?country=IT&format=json&country=IT&bankcode=02008&branch=30545&account=000103685854
MC ?country=MC&format=json&country=MC&bankcode=30002&branch=03260&account=0000079112A
MR ?country=MR&format=json&bankcode=00012&branch=00001&account=00000078326
MT ?country=MT&format=json&bankcode=07113&account=199008240010
NO ?country=NO&format=json&account=96803502045
PT ?country=PT&format=json&bankcode=0038&branch=0000&cd=81&account=39551148771
SE ?country=SE&format=json&bankcode=9150&account=0092395696
SM ?country=SM&format=json&country=SM&bankcode=03034&branch=09800&account=000060164676
CZ ?country=CZ&format=json&prefix=51&account=1707230277&bankcode=0100
AL ?country=AL&format=json&bankcode=20511117&account=374362CLPRCFEURC
SK ?country=SK&format=json&prefix=&account=4110053902&bankcode=3100
SI ?country=SI&format=json&bankcode=33000&account=0000102423
PL ?country=PL&format=xml&bankcode=11402004&account=0000360275244226
SE ?country=SE&format=json&bankcode=9300&account=5913222524
NL ?country=NL&format=json&account=0006642318




6. API XML Response Structuur


Een gedetailleerde beschrijving van de mogelijke response-velden:

Veldnaam Type Beschrijving
address String Adres van de bank
bank String Naam van de bank
bic String BIC (Bank Identifier Code) van de bank
branch String Naam van de tak volgens bankcode
city String Naam van de stad van de tak
country String 2-letter voorbeeld van een landcode: UK, DE, ...
email String E-mail toegewezen voor contact
fax String Fax van de bank/tak
phone String Telefoon van de bank
state String Land van de bank
website String Website van de bank
zip String Postcode van de bank
Het API-systeem geeft resultaten terug in XML of JSON-formaat, deze zijn eenvoudig te verwerken in meerdere programmeertalen.

Een voorbeeld XML-antwoord van de API voor het Verenigd Koninkrijk ziet er als volgt uit:

Query URL:

?api_key=9834hAHx78ba4g8habsdk&country=GB&format=json&bankcode=110377&account=10218962

<result>
<iban>GB20ULSB98006054100029</iban>
<account>54100029</account>
<sort_code>980060</sort_code>
<bank>ULSTER BANK LTD</bank>
<branch>BELFAST CITY OFFICE 1</branch>
<bic>ULSBGB2BXXX</bic>
<address>PO BOX 232 11-16 DONEGALL SQUARE EAST </address>
<city>BT1 5UB</city>
<country>GB<country/>
<phone>028 90244112</phone>
</result>

Het resultaat voor dezelfde opvraging maar met JSON-formatting ziet er zo uit:

"iban":"GB20ULSB98006054100029","account":"54100029","sort_code":"980060","bank":"ULSTER BANK LTD","branch":"BELFAST CITY OFFICE 1","bic":"ULSBGB2BXXX","address":"PO BOX 232 11-16 DONEGALL SQUARE EAST ","city":"BT1 5UB","country":"GB","phone":"028 90244112"



7. API Fouten


In het geval van een fout zal de IBAN Calculatie API een XML of JSON-response retourneren met een foutmelding.
Onderstaand kan je een beschrijving vinden van alle mogelijke fouten die je kan krijgen:

<error>Account Number checksum is invalid.</error>
<error>Account Number (checksum) is not correct.</error>
<error>Account Number has to be 11 characters long</error>
<error>Account Number has to be 14 characters long</error>
<error>Account Number has to be 24 characters long</error>
<error>Account Number is not valid</error>
<error>Account Number of Sort Code is not valid</error>
<error>Account Number prefix too long.</error>
<error>Account Number too long.</error>
<error>Bank/Branch Code / KIB (checksum) is not correct.</error>
<error>Bank Code/ Branch Code/ Account Number too long.</error>
<error>Bank Code/ Branch Code (checksum) is not correct.</error>
<error>Bank Code not valid</error>
<error>Bank Code too long.</error>
<error>Bank Not Found</error>
<error>Bank Not Recognized</error>
<error>BBAN / NIB (checksum) is not correct.</error>
<error>BLZ/Bank Code not valid</error>
<error>Branch/Agencia not found</error>
<error>Branch Code too long.</error>
<error>Branch not found</error>
<error>Check Digit too long.</error>
<error>Clearingnummer/Account Number is not valid. Check digit incorrect.</error>
<error>Clearingnummer / BankCode can not be identified. IBAN can not be calculated.</error>
<error>Clearingnummer or Account Number too long.</error>
<error>Codice ABI della Banca/Bank Code not valid</error>
<error>Codice CAB della Filiale/Branch Code not valid</error>
<error>Country code is not valid</error>
<error>Country or Bank not supported</error>
<error>IBAN is not valid</error>
<error>Kontonummer/Account Number is not valid</error>
<error>Missing fields</error>
<error>Non FR IBAN</error>
<error>Non FR IBAN country</error>
<error>Required field is missing. Please enter Bank Code and Account Number</error>
<error>Required fields not submitted.</error>
<error>RIB is not valid</error>
<error>SortCode / BankCode can not be identified. IBAN can not be calculated.</error>
<error>Sort code cannot be found</error>