Documentation API de calcul d'IBAN

Cette API fait partie de notre IBAN Suite offert par notre société.

Guide d'intégration API

1. QU'EST-CE QUE L'API DE CALCUL D' IBAN

Le moteur IBAN Calculation (aussi appelé IBAN Conversion) est un logiciel permettant à nos clients de convertir les combinaisons de codes bancaires et de numéros de compte nationaux en numéros IBAN (International Bank Account Numbers) valides.

Le système permet à l'interface manuelle de nos clients ainsi qu'à une API de permettre l'intégration dans les systèmes internes de leur entreprise.

Le système identifie également les banques et les institutions financières et fournit les détails à nos clients.

2. Fonctionnalités

Voici quelques-unes des principales fonctionnalités de notre moteur de calcul IBAN:

  • Valider les sommes de contrôle du code de banque / numéro de compte local (* voir les pays pris en charge)
  • Récupérer des informations sur la banque en fonction du code de banque / succursale local.
  • Générer automatiquement un format IBAN valide pour le code de banque / succursale et le numéro de compte fournis.
  • Le système prend en charge le formatage de réponses multiples ( JSON / XML )


3. Pays pris en charge

L'API de calcul IBAN prend actuellement en charge les pays suivants et les champs requis par notre API pour calculer un IBAN.

Code Pays Nom du Pays Code Banque Branche Compte Les caractères **
AT Autriche OUI   OUI  
BE Belgique OUI   OUI OUI
CH Suisse OUI   OUI  
DE Allemagne OUI   OUI  
EE Estonie     OUI  
ES Espagne OUI OUI OUI OUI
FI Finlande     OUI OUI
FR France OUI OUI OUI OUI
GB Grande-Bretagne OUI   OUI OUI
HU Hongrie     OUI OUI
IE Irlande OUI   OUI OUI
IT Italie OUI OUI OUI OUI
MC Monaco OUI OUI OUI OUI
MR Mauritanie OUI OUI OUI  
MT Malte OUI   OUI  
NO Norvège     OUI OUI
PT Portugal OUI OUI OUI OUI
SM Saint Marin OUI OUI OUI  
CZ République Tchèque OUI   OUI OUI
AL Albanie OUI   OUI  
SK République Slovaque OUI   OUI OUI
SI Slovénie OUI   OUI OUI
PL Pologne OUI   OUI OUI
PK Pakistan OUI   OUI  
SE Suède OUI   OUI OUI
NL Pays-Bas OUI OUI
La colonne Chiffre de contrôle indique si le pays prend en charge le numéro de compte et / ou la validation du code de contrôle du code bancaire.

La validation des chiffres de contrôle est une couche supplémentaire de protection de l'intégrité des données contre les erreurs de frappe.

4. Apports API

L'API accepte les requêtes HTTP GET et POST pour les données d'entrée.
Les paramètres acceptés sont listés dans le tableau ci-dessous:

Champs Nom Type Description
api_key String Votre clé API personnelle. Obtenu dans la zone client.
format String format de réponse API ( xml ou json )
country String 2 lettre du code pays ( UK/US/DE/FR )
bankcode String Un identifiant bancaire unique. Différent pour chaque pays. ( optionnel ). Certains pays exigent uniquement un numéro de compte.
branch String Un identifiant de succursale locale unique ( optionnel )
account String Un numéro de compte personnel
cd Integer Chiffres de contrôle utilisés dans certains pays.
prefix Integer Actuellement requis seulement pour la République tchèque ( optionnel )
Le premier argument est la clé de l'API, c'est une chaîne unique qui aide notre système à vous identifier en tant qu'utilisateur et vous permet d'accéder à l'API.

L'API prend en charge plusieurs formats de réponse afin de faciliter l'intégration. Actuellement, XML et JSON sont pris en charge.

Les arguments Pays doivent être constitués d'un code de pays ISO à 2 lettres, par exemple UK pour le Royaume-Uni, DE pour l'Allemagne, FR pour la France…
Le code bancaire a une longueur et une structure différentes pour chaque pays.

Le code de branche est un argument optionnel requis uniquement pour certains pays (voir les exemples)
Le numéro de compte est requis pour tous les pays et, dans certains cas, c'est le seul paramètre utilisé pour calculer un IBAN.

Les chiffres à cocher sont requis uniquement pour certains pays qui ont incorporé de tels algorithmes de validation dans leur structure de numéro de compte bancaire national. (voir les exemples))

Préfixe est un champ facultatif requis uniquement pour le calcul de l’IBAN en République tchèque.

5. EXEMPLES D’API

Dans le tableau ci-dessous, vous trouverez des exemples de requête GET à notre API pour chaque pays

Pays Exemple de requête (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
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

6. STRUCTURE DE LA REPONSE API XML

Une description détaillée des champs possibles renvoyés peut être vue dans le tableau ci-dessous:

Champs Nom Type Description
address String Adresse de la succursale bancaire ou du siège
bank String Name of the bank or financial institution
bic String BIC ( Bank Identifier Code ) de la banque
branch String Nom de la succursale identifiée par le code bancaire
city String Le nom de la ville dans laquelle la succursale est située.
country String Abréviation en deux lettres du code du pays, par exemple: US, UK, AU, FR … etc.
email String Nom de l'adresse e-mail de contact de la banque ou de la succursale
fax String Numéro Fax de la banque/ succursale
phone String Numéro de téléphone de la banque/ succursale
state String adresse de l'état de la banque/ succursale
website String Adresse du siteweb de la banque/ succursale
zip String Code Postal ou ZIP de l'adresse de la succursale de la banque
Le système API renvoie les résultats au format XML ou JSON, facile à analyser dans une variété de langages de programmation et de plates-formes.

Un exemple de réponse XML de l'API pour un code SORT et une recherche de numéro de compte au Royaume-Uni serait:

URL de requête:

?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>

La réponse pour la même requête si l'utilisateur a spécifié une mise en forme JSON sera:

"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. Erreurs API

En cas d'erreur, l'API de calcul IBAN renvoie une réponse XML ou JSON contenant le message d'erreur.
L' erreur avec les balises XML est renvoyée sans aucun autre champ dans la réponse XML.
Vous trouverez ci-dessous une description de tous les messages d'erreur pouvant être renvoyés:


<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>