Documentation de l'API de Validation IBAN V4

Cette API fait partie de notre IBAN Suite

1. Qu'est-ce qu'il y a de nouveau dans l'API de validation d'IBAN V4?


Nous travaillons constamment à améliorer nos services et à fournir de meilleures solutions de validation des paiements.
Vous avez peut-être remarqué que l'API de la suite IBAN a ignoré une iteration de version, en passant de de V2 à V4
Cela a été fait parce que nous avons uni les autres API telles que SortWare v3 en une seule itération de versionnement, par ex. v4.

Changelog ( de v2 à v4 ):


Nouvelle validation ajoutée (erreur 206 ) – l’API V4 vérifie maintenant les caractères illégaux dans l’IBAN saisi.
Le nouveau code d'erreur - 206 (Échec de la validation) avec message: IBAN contient des caractères non autorisés.
Ce code d'erreur vous donnera plus d'informations dans le cas où vous soumettez un IBAN avec des caractères non alphanumériques dans notre système.
Le comportement précédent consistait à supprimer tous les caractères non alphanumériques et à effectuer la validation

Nouvelle validation ajoutée (erreur 207 ) - Le pays ne prend pas en charge l’IBAN
Cette couche de validation indiquera si le code de pays de l'IBAN soumis ne fait pas partie des pays officiels soutenant les paiements IBAN.
Par exemple, une personne peut générer un IBAN pour les États-Unis en utilisant un logiciel tiers non fiable
Certains IBAN peuvent ressembler à ceci: US64SVBKUS6S3300958879
Vous remarquerez que le chiffre de contrôle est correct et qu'il passera les validations du module, cependant ce n'est pas un IBAN valide puisque les États-Unis n'utilisent pas l'IBAN pour les paiements bancaires.

2. Fonctionnalités


L'API de validation IBAN V4 vous permet de faire ce qui suit:

  • Vérifier si un IBAN est valide en utilisant les chiffres de vérification
  • Vérifier si un IBAN est valide, avec un code de banque national et des chiffres de contrôle* valides
  • Vérifier si la longueur d'un IBAN est spécifique à un pays
  • Vérifier la structure / formatage IBAN pour un pays spécifique
  • Vérifier les caractères IBAN (vérifier les caractères non alphanumériques)
  • Vérifier si le code du pays prend en charge la norme IBAN

  • Identifier la banque qui a émis l'IBAN
  • Identifiez le code de pays d'un IBAN
  • Identifier l'adresse de la banque qui émet l'IBAN
  • Identifier le code BIC de la banque
  • Identifier le support SEPA de la banque: B2B,COR1,SCC,SCT,SDD

* Les validations du code bancaire et du numéro de compte sont effectuées pour certaines banques et certains pays uniquement.

3. Requêtes API V2



Le système API vous permet d'automatiser la validation IBAN via une simple requête HTTP GET ou POST.
Les paramètres acceptés sont listés dans le tableau ci-dessous:

Champs Nom Longueur Type Description
IBAN Max 100 String L'IBAN que vous voulez valider.
api_key 128 String Votre clé API personnelle .
format 5 String Format de la réponse XML et JSON pris en charge.

*Pour obtenir une clé API, contactez-nous sur contact@iban.com ou souscrivez à un abonnement sur notre page de tarifs

EXEMPLE – Valider un IBAN
N'hésitez pas à utiliser l'exemple de code ci-dessous pour tester l'API dans les langages de programmation les plus courants.

?
1
2
3
4
5
curl "https://api.iban.com/clients/api/v4/iban/" \
    -X POST \
    -d format=json \
    -d api_key=[YOUR_API_KEY] \
    -d iban=DE46500700100927353010
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?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);
?>
?
1
2
3
4
5
6
7
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
?
1
2
3
4
5
6
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)
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
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

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
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

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
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);
         
    }
})

Un exemple d'utilisation de l'API de validation IBAN avec une requête GET peut être trouvé ci-dessous:

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

Où:
  • key est votre clé personnelle API
  • IBAN est envoyé pour validation par le module API.
  • xml est le format de la réponse. Un mot-clé json peut également être spécifié pour la réponse au format json

Une fois qu'une requête HTTP GET ou POST est effectuée avec la bonne clé API, le système renvoie les résultats dans le format spécifié. Vous pouvez trouver un exemple de réponse dans la section suivante “Structure de réponse API ”

4. Réponse API V2

Un schéma XSD de la réponse de l'API peut être trouvé ci-dessous:
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementformdefault="qualified" attributeformdefault="unqualified">
<xs:element name="result">
<xs:complextype>
     <xs:sequence>
           <xs:element name="bank_data">
                 <xs:complextype>
                       <xs:sequence>
                             <xs:element name="bic" type="xs:string"></xs:element>
                             <xs:element name="branch"></xs:element>
                             <xs:element name="bank" type="xs:string"></xs:element>
                             <xs:element name="address"></xs:element>
                             <xs:element name="city" type="xs:string"></xs:element>
                             <xs:element name="state"></xs:element>
                             <xs:element name="zip" type="xs:int"></xs:element>
                             <xs:element name="phone"></xs:element>
                             <xs:element name="fax"></xs:element>
                             <xs:element name="www"></xs:element>
                             <xs:element name="email"></xs:element>
                             <xs:element name="country" type="xs:string"></xs:element>
                             <xs:element name="country_iso" type="xs:string"></xs:element>
                             <xs:element name="account" type="xs:int"></xs:element>
                             <xs:element name="bank_code" type="xs:int"></xs:element>
                             <xs:element name="branch_code"></xs:element>
                       </xs:sequence>
                 </xs:complextype>
           </xs:element>
           <xs:element name="sepa_data">
                 <xs:complextype>
                       <xs:sequence>
                             <xs:element name="SCT" type="xs:string"></xs:element>
                             <xs:element name="SDD" type="xs:string"></xs:element>
                             <xs:element name="COR1" type="xs:string"></xs:element>
                             <xs:element name="B2B" type="xs:string"></xs:element>
                             <xs:element name="SCC" type="xs:string"></xs:element>
                       </xs:sequence>
                 </xs:complextype>
           </xs:element>
           <xs:element name="validations">
                 <xs:complextype>
                       <xs:sequence>
                             <xs:element name="chars">
                                   <xs:complextype>
                                         <xs:sequence>
                                               <xs:element name="code" type="xs:int"></xs:element>
                                               <xs:element name="message" type="xs:string"></xs:element>
                                         </xs:sequence>
                                   </xs:complextype>
                             </xs:element>
                             <xs:element name="iban">
                                   <xs:complextype>
                                         <xs:sequence>
                                               <xs:element name="code" type="xs:int"></xs:element>
                                               <xs:element name="message" type="xs:string"></xs:element>
                                         </xs:sequence>
                                   </xs:complextype>
                             </xs:element>
                             <xs:element name="account">
                                   <xs:complextype>
                                         <xs:sequence>
                                               <xs:element name="code" type="xs:int"></xs:element>
                                               <xs:element name="message" type="xs:string"></xs:element>
                                         </xs:sequence>
                                   </xs:complextype>
                             </xs:element>
                             <xs:element name="structure">
                                   <xs:complextype>
                                         <xs:sequence>
                                               <xs:element name="code" type="xs:int"></xs:element>
                                               <xs:element name="message" type="xs:string"></xs:element>
                                         </xs:sequence>
                                   </xs:complextype>
                             </xs:element>
                             <xs:element name="length">
                                   <xs:complextype>
                                         <xs:sequence>
                                               <xs:element name="code" type="xs:int"></xs:element>
                                               <xs:element name="message" type="xs:string"></xs:element>
                                         </xs:sequence>
                                   </xs:complextype>
                             </xs:element>
                             <xs:element name="country_support">
                                   <xs:complextype>
                                         <xs:sequence>
                                               <xs:element name="code" type="xs:int"></xs:element>
                                               <xs:element name="message" type="xs:string"></xs:element>
                                         </xs:sequence>
                                   </xs:complextype>
                             </xs:element>
                       </xs:sequence>
                 </xs:complextype>
           </xs:element>
           <xs:element name="errors"></xs:element>
     </xs:sequence>
</xs:complextype>
</xs:element>
</xs:schema>
Une description détaillée des champs d'objet bank_data renvoyés peut être vue dans le tableau ci-dessous :

Champs Nom Longueur Type Description
BIC Max 11 String Le code BIC de la banque / branche ou institution émettrice.
BANK Max 256 String Le nom de la banque / institution qui a émis l'IBAN
BRANCH Max 256 String Nom de la succursale bancaire spécifique si disponible
COUNTRY Max 32 String Nom complet du pays d'oigine, par exemple : États-Unis d'Amérique
COUNTRY_ISO 2 String Deux lettres d'abréviation du pays, par exemple US, UK, AU, FR … etc.
CITY Max 128 String Le nom de la ville où se trouve la banque émettrice.
STATE Max 128 String Le nom de l'État dans laquelle la banque/succursale est localisée.
ZIP Max 11 String Code Postale ou ZIP de la ville.
ADDRESS Max 128 String L'adresse de la banque émettrice.
ACCOUNT Max 128 String Le numéro de compte bancaire domestique extrait de l'IBAN.
Une description détaillée des champs d'objet sepa_data renvoyés peut être vue dans le tableau ci-dessous:

Champs Nom Longueur Type Description
SCT Max 3 String Cette banque prend en charge le transfert de crédit SEPA.
SDD Max 3 String Cette banque prend en charge les débit direct SEPA .
COR1 Max 3 String Cette banque prend en charge SEPA COR1.
B2B Max 3 String Cette banque prend en charge SEPA "Business to Business".
SCC Max 3 String WCette banque prend en charge la compensation de carte SEPA.


Un exemple de réponse XML de l'API pour une requête de validation IBAN serait:
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
<result>
    <bank_data>
        <bic>BARCGB22</bic>
        <branch>INTERNATIONAL BANKING 2</branch>
        <bank>BARCLAYS BANK UK PLC</bank>
        <address>PO Box 69999 1 Churchill Place Canary Wharf </address>
        <city>London</city>
        <state>
        <zip>E14 1QE</zip>
        <phone>020 71147000</phone>
        <fax>
        <www>
        <email>
        <country>
        <country_iso>GB</country_iso>
        <account>73160944</account>
    </country></email></www></fax></state></bank_data>
    <sepa_data>
        <sct>YES</sct>
        <sdd>YES</sdd>
        <cor1>YES</cor1>
        <b2b>YES</b2b>
        <scc>NO</scc>
    </sepa_data>
    <validations>
        <chars>
            <code>006</code>
            <message>IBAN does not contain illegal characters</message>
        </chars>
        <iban>
            <code>001</code>
            <message>IBAN Check digit is correct</message>
        </iban>
        <account>
            <code>002</code>
            <message>Account Number check digit is correct</message>
        </account>
        <structure>
            <code>005</code>
            <message>IBAN structure is correct</message>
        </structure>
        <length>
            <code>003</code>
            <message>IBAN Length is correct</message>
        </length>
        <country_support>
            <code>007</code>
            <message>Country supports IBAN standard</message>
        </country_support>
    </validations>
    <errors>
</errors></result>

5. Statut du code API V2

Les validations mathématiques des chiffres de contrôle sont renvoyées dans l'objet "validations"

Statut du code Type Description
301 Erreur compte La clé API est invalide
302 Erreur compte Abonnement expiré
303 Erreur compte Aucune requête disponible
304 Erreur compte Vous n'avez pas accès à cette API
201 Échec de Validation Le numéro de contrôle du numéro de compte est incorrect
202 Échec de validation Le chiffre de contrôle de l'IBAN n'est pas correcte
203 Échec de validation La longueur de l'IBAN n'est pas correcte
205 Échec de validation La structure de l'IBAN n'est pas correcte
206 Échec de validation L'IBAN contient des caractères interdits
207 Échec de validation Le pays ne prends pas en charge l' IBAN
001 Succès de la Validation Le chiffre de contrôle de l'IBAN est correct
002 Succès de la Validation Le chiffre de contrôle du numéro de compte est correct
003 Succès de la Validation La longueur de l'IBAN Length est correct
004 Succès de la Validation Le numéro de compte ne prend pas en charge le chiffre de contrôle
005 Succès de la Validation La structure de l'IBAN est correcte
006 Succès de la Validation L'IBAN ne contient aucun caractère illégal
007 Succès de la Validation Pays prend en charge la norme IBAN