This API is part of our IBAN Suite service
API integration guide
1. What is the IBAN Calculation API?
The IBAN Calculation ( AKA IBAN Conversion ) engine is a software system allowing our clients to convert domestic bank code and account number combinations into validated International Bank Account Numbers ( IBAN ).The system allows our clients manual interface as well as an API to allow integration in their company’s internal systems.
The system also identifies the banks and financial institutions and provides the details to our customers.
2. Features
Below are some of the key features of our IBAN Calculation engine:- Validate local bank code / account number checksums ( * see Supported Countries )
- Retrieve information about the bank based on the local bank/branch code.
- Automatically generates a valid IBAN format for the supplied bank/branch code and account number
- System supports multiple response formatting ( JSON / XML )
3. Supported Countries
The IBAN Calculation API currently supports the following countries and the fields required by our API to calculate an IBAN.| Country Code | Country Name | BankCode | Branch | Account | Check Digit Validation** |
|---|---|---|---|---|---|
| AT | Austria | YES | YES | ||
| BE | Belgium | YES | YES | YES | |
| CH | Switzerland | YES | YES | YES | |
| DE | Deutschland | YES | YES | YES | |
| EE | Estonia | YES | YES | ||
| EG | Egypt | YES | YES | YES | |
| ES | Spain | YES | YES | YES | YES |
| FI | Finland | YES | YES | ||
| FR | France | YES | YES | YES | YES |
| GB | Great Britain | YES | YES | YES | |
| HU | Hungary | YES | YES | ||
| IE | Ireland | YES | YES | YES | |
| IT | Italy | YES | YES | YES | YES |
| MC | Monaco | YES | YES | YES | YES |
| MR | Mauritania | YES | YES | YES | |
| MT | Malta | YES | YES | ||
| NO | Norway | YES | YES | ||
| PT | Portugal | YES | YES | YES | YES |
| SM | San Marino | YES | YES | YES | YES |
| CZ | Czech Republic | YES | YES | YES | |
| AL | Albania | YES | YES | ||
| SK | Slovak Republic | YES | YES | YES | |
| SI | Slovenia | YES | YES | YES | |
| PL | Poland | YES | YES | YES | |
| PK | Pakistan | YES | YES | ||
| SE | Sweden | YES | YES | YES | |
| NL | Netherlandds | YES | YES | ||
| AD | Andorra | YES | YES | ||
| HR | Croatia | YES | YES | YES | |
| CY | Cyprus | YES | YES | ||
| DK | Denmark | YES | YES | YES | |
| GR | Greece | YES | YES | ||
| IS | Iceland | YES | YES | YES | YES |
| IL | Israel | YES | YES | YES | |
| LI | Liechtenstein | YES | YES | YES | |
| LT | Lithuania | YES | YES | ||
| BH | Bahrain | YES | YES | ||
| BR | Brazil | YES | YES | ||
| DO | Dominican Republic | YES | YES | ||
| SV | El Salvador | YES | YES | ||
| FO | Faroe Islands | YES | YES | YES | |
| GL | Greenland | YES | YES | YES | |
| GT | Guatemala | YES | YES | ||
| IL | Israel | YES | YES | YES | |
| KW | Kuwait | YES | YES | ||
| MD | Moldova | YES | YES | ||
| QA | Qatar | YES | YES | ||
| SA | Saudi Arabia | YES | YES | ||
| UA | Ukraine | YES | YES | ||
| AE | United Arab Emirates | YES | YES |
The check digits validation is an extra layer of data integrity protection against typing errors.
4. API Inputs
The API accepts both HTTP GET and POST request for input data.The accepted parameters are listed in the table below:
| Field Name | Type | Description |
|---|---|---|
| api_key | String | Your personal API key. Obtained in the client area. |
| format | String | API response format ( xml or json ) |
| country | String | 2 letter country code ( UK/US/DE/FR ) |
| bankcode | String | A unique bank identifier. Different for each country. ( optional ). Some countries only require account number. |
| branch | String | A unique local branch identifier ( optional ) |
| account | String | Personal account number |
| cd | Integer | Check Digits used in some countries. |
| prefix | Integer | Currently required only for Czech Republic ( optional ) |
The API supports multiple response formats in order to provide easier integration. Currently, XML and JSON are supported.
The Country arguments must consist of a 2 letter ISO country code such as UK for United Kingdom, DE for Germany, FR for France …
Bank Code has a different length and structure for each country.
Branch Code is an optional argument is only required for some countries ( refer to Examples )
Account number is required for all countries and in some cases it is the only parameter used to calculate an IBAN.
Check Digits is required only for certain countries which have incorporated such validation algorithms in their domestic bank account number structure. ( refer to Examples )
Prefix is a field optionally required only for Czech Republic IBAN calculation.
5. API Examples
In the table below you can find the example working GET query to our API for each country.| Country | Example 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 |
| FR | ?country=FR&format=json&rib=40031000010000100222L41 |
| 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 |
| PK | ?country=PK&format=json&bankcode=HABBPKKA&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 |
| AD | ?country=AD&bankcode=00080001&account=1234567890 |
| HR | ?country=HR&bankcode=2360000&account=1101234565 |
| CY | ?country=CY&bankcode=00200195&account=357001234567 |
| DK | ?country=DK&bankcode=2000&account=123456789 |
| GR | ?country=GR&bankcode=0810001&account=1234567890 |
| IS | ?country=IS&bankcode=0001&acc_type=12&account=123456&kennitala=3108962099 |
| LI | ?country=LI&bankcode=08810&account=0418650028 |
| LT | ?country=LT&bankcode=10100&account=12345678901 |
| BH | ?country=BH&bankcode=CITI&account=1077181611 |
| BR | ?country=BR&bankcode=00000000&account=10932840814P2 |
| DO | ?country=DO&bankcode=ACAU&account=123456789 |
| SV | ?country=SV&bankcode=ACAT&account=123123 |
| FO | ?country=FO&bankcode=6460&account=0123456789 |
| GL | ?country=GL&bankcode=6471&account=0123456789 |
| GT | ?country=GT&bankcode=AGRO&account=1234567890 |
| IL | ?country=IL&bankcode=010&branch=800&account=12612345 |
| KW | ?country=KW&bankcode=CBKU&account=1234560101 |
| MD | ?country=MD&bankcode=EX&account=1234567 |
| QA | ?country=QA&bankcode=QNBA&account=693123456 |
| SA | ?country=SA&bankcode=20&account=1234567891234 |
| UA | ?country=UA&bankcode=305299&account=2990004149123456789 |
| AE | ?country=AE&bankcode=009&account=0000000123456789 |
6. API XML Response Structure
A detailed description of the possible fields returned can be seen in the table below:| Field Name | Type | Description |
|---|---|---|
| address | String | Address of the bank branch or headquarters |
| bank | String | Name of the bank or financial institution |
| bic | String | BIC ( Bank Identifier Code ) of the bank |
| branch | String | Name of the branch identified by the bank code |
| city | String | The name of the city in which the branch is located. |
| country | String | Two letter abbreviation of the country code e.g. US, UK, AU, FR … etc. |
| String | Appointed contact email address for the bank or branch | |
| fax | String | Fax number of the bank/branch |
| phone | String | Contact phone number of the bank / branch |
| state | String | State of the bank/branch address |
| website | String | Website address of the bank / branch |
| zip | String | ZIP or Postal code of the bank branch address |
A sample XML reply from the API for a United Kingdom SORT code and Account Number search would be:
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>
The response for the same query if user specified a JSON formatting will be:
"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 Errors
In case of an error the IBAN Calculation API returns an XML or JSON response containing the error message.The <error></error> XML tags are returned without any other fields in the XML response.
Below you can find a description of all possible error messages that could be returned:
<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>