API de VALIDATION du code BIC / SWIFT

Comment intégrer l'API de validation BIC dans votre logiciel

1. Qu'est-ce que l'API de validation BIC ?

Lors du traitement des paiements par virement et du traitement des transactions liées à l'IBAN, il est essentiel de fournir le bon code SWIFT / BIC pour pouvoir effectuer des paiements.
Notre société a accordé une licence au répertoire BIC officiel de S.W.I.F.T SCRL pour fournir un moyen simple et puissant de valider BIC automatiquement. Ce service vous permet d'intégrer la recherche d'annuaire de code BIC dans votre logiciel à des fins internes

L'API de validation BIC contient des données SWIFTRef Inside. Données BIC utilisées avec la permission de S.W.I.F.T. SCRL. Droits de base de données réservés 2018

2. Fonctionnalités

Principales fonctionnalités de l'API de validation BIC:

  • Récupérez des informations sur la banque en fonction du code BIC.
  • Recherchez dans le répertoire BIC une partie du nom de la banque et du pays.
  • Recherchez dans le répertoire BIC pour les enregistrements historiques.
  • Utilisez à la fois la réponse API complète et simplifiée pour une intégration plus facile.


3. Utilisation API

L'API de validation BIC est basée sur REST et prend en charge les requêtes HTTP GET ou POST simples.

Les paramètres acceptés sont listés dans le tableau ci-dessous:

Champs Nom Longueur Type Description
bic 11 String Code BIC / SWIFT à chercher. Peut être de 8 ou 11 caractères.
bank_name 256 String Une partie d'un nom de banque pour effectuer une recherche dans le repertoire BIC.
country 2 String Deux lettres du code pays. Requis pour chercher par nom de banque.
api_key 128 String Votre clé API personnel.
format 4 String Obligatoire pour spécifier le format des données renvoyées. Valeurs actuellement supportées: json, xml
limit Integer Optionnel: peut être utilisé pour limiter le nombre de résultats lors de la recherche par nom de banque.
hist integer Optionnel: peut être utilisé pour afficher les enregistrements historiques de la base de données pour la recherche de banque et BIC.
À l'intérieur de votre portail en ligne, vous pouvez trouver votre clé d'API et votre URL de point de terminaison de demande, utilisée pour sécuriser les requêtes de recherche.


4. Structure de réponse API XML

Vous pouvez télécharger Shéma XSD de la réponse de l'API.
Une description détaillée des champs retournés peut être vue dans le tableau ci-dessous:

Champs Nom Type Longueur Toujours présent Description
MODIFICATION FLAG Alphabétique 1 Oui Dans delta files:
• A (addition)
• M (modification)
• D (suppression) dans tous les fichiers:
• A (addition)
CHANGED FIELD Numérique 186 Non Enregistre le champ (ou TAG) qui a été modifié suite à une modification d'un enregistrement ou à la suite d'un nouvel EVENT.
Une ou plusieurs colonnes sont indiquées sous la forme d'une séquence de nombres, chaque chiffre représentant la colonne ayant été modifiée à partir de l'instance d'enregistrement précédente ou du précédent EVENT. Exemple "6,7,8,9"
Cela signifie que le EVENT TYPE, EVENT DATE, BIC8, et le BIC BRANCHE ont changé.
Les CHAMPS suivants sont exclus de l’enregistrement dans CHANGED FIELD:
• RECORD KEY
• CHANGED FIELD
• MODIFICATION FLAG
CLE D'ENREGISTREMENT Alphanumérique 12 Oui La clé unique du disque dans le fichier
Chaque enregistrement représente un événement dans le cycle de vie BIC.
Une fois assignée, le RECORD KEY ne change jamais.
PREVIOUS RECORD KEY Alphanumerique 12 Non Le RECORD KEY du précédent EVENT lié
Tous les événements liés sont liés et peuvent être localisés en utilisant cette information.
NEXT RECORD KEY Alphanumerique 12 Non LE RECORD KEY ( Clé d'enregistrement) de l'événement lié suivant
Tous les événements liés sont liés et peuvent être localisés en utilisant cette information
EVENT TYPE Alphabetique 32 Oui Le EVENT ou changer la description liée au BIC qui a eu lieu dans le passé, dans le présent, ou se produira dans le futur.
Types d'Event :
• BIC ISSUED
• BIC EXPIRED
• BIC ACTIVATED ON FIN
• BIC ACTIVATED ON FA
• BIC ACTIVATED ON IA
• BIC DEACTIVATED ON FIN
• BIC DEACTIVATED ON FA
• BIC DEACTIVATED ON IA
• BIC DEACTIVATED
• BIC SUSPENDED
• BIC REACTIVATED
• BIC PUBLISHED
• BIC LEGAL NAME CHANGED
• BIC INSTITUTION NAME CHANGED
• BIC ADDRESS CHANGED
• FIN SERVICE CODE CHANGED
La dernière date de mise à jour est la dernière ligne de la séquence BIC (c'est-à-dire l'entrée la plus récente).
Quand un nouvel EVENT est ajouté, le MODIFICATION FLAG et CHANGED
La colonne FIELD sera mis à jour dans l'immédiat lié à EVENT.
DATE DE L'EVENT Alphanumerique 8 Oui La date de l' EVENT
BIC8 Alphanumerique 8 Oui BIC (institution, pays, et la partue suffixe) où :
• Partie prefixe (4 caractères)
• Code Pays(2 caractères)
• Partie suffixe (2 caractères)
BIC SUCCURSALE Alphanumerique 3 Oui L'identifiant de la succursale BIC associé au BIC à 8 caractères. Si aucun identificateur de branche n'existe, alors XXX est utilisé.
BIC Alphanumerique 11 Oui Le BIC entier: BIC de 8-caractères BIC et indentifiant de banque
RECORD STATUS Alphabetique 1 Oui Indique le statut d'un enregistrement:
• [C] = Représentant le dernier événement de la chaîne jusqu'à la date de publication, à l'exclusion de [F]uture events
• [H] = Enregistrements historiques dans la chaîne d'événements
• [F] = Événement futur qui se produira après la date de publication de l'annuaire. L'événement [C] urrent indiqué précédemment sera valable jusqu'à la date spécifiée dans le [F]uture event.
Pour les FUTURE events, la date indique quand le changement sera VALID FROM.
OPERATIONALLY ACTIVE RECORD Alpha 1 Oui Il existe plusieurs enregistrements pour le même BIC. Ce champ indique lequel des enregistrements du même BIC est le BIC actif et doit être utilisé.
• [Y] Operationellement actif
• [N] Operationellement inactif
Pour chaque BIC unique, il y a une seule entrée d'enregistrement indiquant un statut ACTIVE (Y).
L'enregistrement avec un statut [H]istorical va toujours indiquer [N].
L'enregistrement avec [C]urrent peut indiquer [Y] ou [N].
L'enregistrement avec [F] va toujours indiquer [N].
SUBTYPE INDICATOR Any type 4 Oui Le type d'entreprise de l'entité. L'indicateur de sous-type est fourni uniquement pour les enregistrements avec un BIC.
SWIFT FIN Alphabetique 1 Oui Statut de l'accessibilité d'une entité à travers FIN:
• [Y] connecté à FIN
• [N] non connecté à FIN
SWIFT FA Alphabetique 1 Oui Statut de l'accessibilité d'une entité à travers FileAct:
• [Y] connecté à FileAct
• [N] non connecté à FileAct
SWIFT IA Alpha 1 Oui Statut de l'accessibilité d'une entité à travers InterAct:
• [Y] connecté à InterAct
• [N] non connecté à InterAct
NOM LÉGAL Any 105 Non Nom légal de l'institution
NOM DE L'INSTITUTION Any 105 Oui Nom de l'institution (nom publié)
TYPE D'INSTITUTION Alphabetic 12 Oui Organisation principalement engagée dans l'intermédiation financière et / ou dans des activités financières auxiliaires
Type d'institution:
• FINANCIAIRE
• NON FINANCIÈREL
TYPE D'ENTITÉ Alphabetique 16 Oui Identifie le type de l'entité financière:
• Entité Légale
• Branche
• Opérationnelle
RE ADRESSE 1 Any 35 Non [Registration] Nom de rue
RE ADRESSE 2 Any 35 Non [Registration] nom de rue
RE ADRESSE 3 Any 35 Non [Registration] immeuble, nom de l'immeuble, étage
RE ADRESSE 4 Any 35 Non [Registration] RÉGION
RE CITY Any 35 Non [Registration] Nom de la ville de l'institution / de la succursale
RE CPS Any 90 Non [Registration] Comté, province, état ou autre région administrative de l'institution / succursale propriétaire
RE ZIP CODE Any 15 Non [Registration] Code Postale de l' institution/ succursale
RE POB NUMÉRO Any 35 Non Champ séparé par des virgules avec le numéro POB de l'institution / succursale et le code postal associé.
Exemple
"POB 103352, 40024"
Cela permet aux clients d'utiliser l'adresse POB complète:
POB 103352
40024, DUESSELDORF (VILLE)
OP ADRESSE 1 Any 35 Non [Operationnel] nom de la rue
OP ADRESSE 2 Any 35 Non [Operationnel] Numéro de rue
OP ADRESSE 3 Any 35 Non [Operationnel] Bâtiment, nom du bâtiment, étage
OP ADRESSE 4 Any 35 Non [Operational] Région
OP CITY Any 35 Non [Operational] Nom de la ville de l'institution / de la succursale
OP CPS Any 90 Non [Operational] Comté, province, état ou autre région administrative de l'institution / succursale propriétaire
OP CODE ZIP Any 15 Non [Operational] Code Postale de l'institution/ de la succursale
OP POB NUMÉOR Any 35 Non Champ séparé par des virgules avec le numéro POB de l'institution / branche et le code postal correspondant.
Exemple
"POB 103352, 40024"
Cela permet aux clients d'utiliser l'adresse POB complète:
POB 103352
40024, DUESSELDORF (CITY)
BR adresse de la rue 1 Any 35 Non [Branch] Nom de la rue
BR ADRESSE 2 Any 35 Non [Branch] Numéro de rue
BR ADRESSE DE L'IMMEUBLE 3 Any 35 Non [Branche] Immeuble, nom de l'immeuble, étage
BR ADRESSE DE RUE 4 Any 35 Non [Branche] Région
BR VILLE Any 35 Non [Branch] Nom de la ville de l'institution/ succursale
BR CPS Any 90 Non [Branch] Pays, état, ville, ou toute région administrative de l'institution/ succursale.
BR CODE ZIP Any 15 Non [Branche] Code Zip de l'institution/ succursale
BR POB NUMBER Any 35 Non Champ séparé par des virgules avec le numéro POB de l'institution / branche et le code postal correspondant.
ExEmple
"POB 103352, 40024"
Cela permet aux clients d'utiliser l'adresse POB complète:
POB 103352
40024, DUESSELDORF (VILLE)
INFORMATION DE LA SUCCURSALE Any 70 Non Information Pays
Il s'agit d'une description textuelle de la succursale, fournie gratuitement par l'institution financière à laquelle elle appartient. Pour le moment, il ne sera fourni que pour les entrées avec un BIC et uniquement lorsque l'institution financière concernée souhaite fournir ces informations supplémentaires. L'information provient du répertoire BIC.
NOM DU PAYS Any 70 Oui Le nom du pays de l'institution / de la succursale tel qu'indiqué dans la norme ISO 3166
ISO CODE PAYS Alphabetic 2 Oui Le code ISO 3166-1 alpha-2 du pays de l'institution/succersale
CODE LOCATION Any type 1 Oui Contient la location (formellement en position 7 du BIC standard:2009)
ExEmples:
• En FR, BICs dans Paris = P
• En BE, BICs dans Bruxelles = B
• En US, BICs dans Côte Est = 3
SERVICE CODES FIN Any type 60 Non Codes de service FIN (également appelés codes de service à valeur ajoutée). Les codes de service sont fournis uniquement pour les enregistrements contenant un code BIC.
Le champ peut contenir jusqu'à 20 codes à trois caractères dans l'ordre alphabétique.
CLÉ D'ENREGISTREMENT BDP Alphanumerique 12 Non La clé unique de l'enregistrement Bank Directory Plus dans le fichier.
CHAMPS A Any 1 Non Réservé pour un prochain usage
CHAMPS B Any 64 Non Réservé pour un prochain usage
CHAMPS C Any 128 Non Réservé pour un prochain usage
CHAMPS D Any 256 Non Réservé pour un prochain usage
CHAMPS E Any 11 Non Réservé pour un prochain usage
CHAMPS F Any 12 Non Réservé pour un prochain usage
Le système API renvoie les résultats au format XML, facile à analyser dans une variété de langages de programmation et de plates-formes.

Un exemple de réponse XML de l'API pour une recherche BIC serait:


<result>
<bicdata>
<row>
<modification_flag>A</modification_flag>
<changed_field>34</changed_field>
<record_key>BP0000004OQQ</record_key>
<previous_record_key>BP00000030XZ</previous_record_key>
<next_record_key/>
<event_type>BIC ADDRESS CHANGED</event_type>
<event_date>20150606</event_date>
<bic8>BARCGB22</bic8>
<branch_bic>XXX</branch_bic>
<bic>BARCGB22XXX</bic>
<record_status>C</record_status>
<operationally_active_record>Y</operationally_active_record>
<subtype_indicator>SUPE</subtype_indicator>
<swift_fin>Y</swift_fin>
<swift_fa>N</swift_fa>
<swift_ia>N</swift_ia>
<legal_name>BARCLAYS BANK PLC</legal_name>
<institution_name>BARCLAYS BANK PLC</institution_name>
<institution_type>FINANCIAL</institution_type>
<entity_type>Legal Entity</entity_type>
<re_street_address_1>1, CHURCHILL PLACE</re_street_address_1>
<re_street_address_2/>
<re_street_address_3/>
<re_street_address_4/>
<re_city>LONDON</re_city>
<re_cps/>
<re_zip_code>E14 5HP</re_zip_code>
<re_pob_number/>
<op_street_address_1>1 CHURCHILL PLACE</op_street_address_1>
<op_street_address_2/>
<op_street_address_3/>
<op_street_address_4/>
<op_city>LONDON</op_city>
<op_cps>LONDON E14 5HP</op_cps>
<op_zip_code/>
<op_pob_number/>
<br_street_address_1/>
<br_street_address_2/>
<br_street_address_3/>
<br_street_address_4/>
<br_city/>
<br_cps/>
<br_zip_code/>
<br_pob_number/>
<branch_information>(ALL U.K. OFFICES)</branch_information>
<country_name>UNITED KINGDOM</country_name>
<iso_country_code>GB</iso_country_code>
<location_code>2</location_code>
<fin_service_codes>EBAERPFINSCOSTGTGT</fin_service_codes>
<record_key_bdp>BD00000006FO</record_key_bdp>
<field_a/>
<field_b/>
<field_c/>
<field_d/>
<field_e/>
<field_f></field_f>
</row>
</bicdata>
<errors/>
</result>




5. Erreurs API

En cas d'erreur, l'API renvoie une réponse XML contenant le message d'erreur.

Le les balises XMLsont renvoyées 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:

Code Statut 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 à cet API
401 Erreur d'entrée Longueur SWIFT acceptée "8 ou 11 caractères'
402 Erreur d'entrée Nom de la banque invalide! La recherche de banque doit comporter au moins 4 caractères.
Caractères autorisés a-z, A-Z, 0-9, [espace]!
403 Erreur d'entrée Code de pays incorrect! Autorisé est un code de pays à 2 lettres. Exemple: UK, DE, FR