Contrôles bancaires et indicateurs de conformité
Cette route ajoute des indicateurs au niveau de la banque, avec screening des listes annoncées (OFAC, EU, UN), données pays/GAFI, joignabilité SEPA et présence au registre VoP. Elle ne vérifie ni le titulaire, ni l’existence du compte, ni le nom du bénéficiaire, et n’exécute aucun paiement. Ce n’est pas un produit AML/CFT réglementé.
POST https://api.ibanforge.com/v1/iban/complianceAppeler avec une clé
Une clé API ou un paiement x402 est nécessaire ; l’essai sans clé de la validation unitaire ne couvre pas cette route. Avec une clé, un appel consomme une unité de franchise ou un crédit prépayé et cost_usdc vaut 0. Avec x402, l’appel coûte 0,02 USDC. Voir clés API, tarifs et x402.
La variable d’environnement IBANFORGE_API_KEY contient votre clé existante, côté serveur. Les valeurs utilisées sont des exemples documentaires. Envoyer soit iban, soit bic, jamais les deux non vides.
curl --fail-with-body --silent --show-error \
https://api.ibanforge.com/v1/iban/compliance \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${IBANFORGE_API_KEY:?}" \
-d '{"iban":"DE89370400440532013000"}'curl --fail-with-body --silent --show-error \
https://api.ibanforge.com/v1/iban/compliance \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${IBANFORGE_API_KEY:?}" \
-d '{"bic":"COBADEFFXXX"}'Le chemin bic reçoit un BIC de 8 ou 11 caractères. Il ne vérifie aucun IBAN. Son enveloppe contient bic (chaîne), bic8, valid_format, found, institution, country, compliance, meta, cost_usdc et processing_ms, ainsi qu’une éventuelle note. found: false signifie que l’annuaire n’a pas nommé l’établissement ; cela n’empêche pas le contrôle par BIC. Cette enveloppe diffère du chemin IBAN, où bic est un objet lorsqu’il est présent.
Lire les résultats avant le score
Le chemin IBAN conserve les champs de la validation unitaire et ajoute compliance et meta. Un 200 peut contenir un IBAN invalide. L’objet checks, lorsqu’il est présent, distingue aussi les axes de contrôle. Les données manquantes ne deviennent pas des résultats négatifs.
Champ dans compliance | Lecture |
|---|---|
sanctions.bank_screened | Une banque a été comparée aux listes chargées ; true ne garantit pas que toutes les listes annoncées étaient disponibles. |
sanctions.institution_listed | true : correspondance trouvée ; false : aucune dans le périmètre consulté complet ; null : aucun constat négatif possible, faute de banque contrôlée ou de liste disponible. |
sanctions.bank_sanctioned, matched_lists | Champs historiques du résultat. Ne pas interpréter un false ou une liste vide sans les champs de couverture et les drapeaux. |
sanctions.payee_screened | Toujours false : aucun criblage du nom du titulaire. |
sanctions.country_sanctioned | Signal pays de la base, distinct de la désignation d’une banque et d’une appréciation juridique d’une transaction. |
sanctions.fatf_status | member, suspended, grey_list, black_list ou non_member. La non-appartenance n’équivaut pas à une inscription sur une liste de risque. |
reachability.screened | La route a pu établir une réponse : registre bancaire consulté ou pays hors périmètre SEPA. |
reachability.sct, sdd, sepa_instant | Indicateurs de schémas ; sans contrôle, les false sont des valeurs par défaut. |
reachability.listed_in_epc_registers | Au moins un schéma disponible ; null si non établi. Lire aussi screened et la provenance. |
vop.screened, register_status | Statut du registre : active, pending, inactive, not_listed ou null si non établi. |
vop.participant, status | Champs historiques : participant est vrai pour active, status utilise encore not_found. Ce n’est pas une comparaison nom/IBAN. |
reachability.source, as_of ; vop.source, as_of | Crédit EPC et date d’extraction quand le registre a été consulté pour la banque ; absents lorsque le pays répond. Date null si inconnue. |
finma_register | IBAN suisse valide seulement. listed : la banque a été rattachée par identifiants à une copie datée du registre public de la FINMA, avec les libellés officiels tels quels. not_verified : pas de réponse, reason dit pourquoi ; cela ne veut jamais dire « non autorisée ». Hors du score. |
risk_score | Score éditorial 0–100 et catégorie ; null / unassessable si l’IBAN est invalide. Ce n’est ni une probabilité de fraude ni une autorisation. |
risk_level | low (0–19), medium (20–39), elevated (40–59), high (60–79), critical (80–100), unassessable. |
flags | Constats et limites lisibles par machine, y compris les sources indisponibles. Tous les drapeaux n’ajoutent pas de points. |
Cas à distinguer
Un IBAN invalide rend risk_score: null, risk_level: "unassessable" et le drapeau iban_invalid. Si l’IBAN est valide mais qu’une source ne répond pas, les axes encore lisibles peuvent répondre ; examiner les champs de couverture, les null et les drapeaux *_unavailable. Un score numérique peut donc accompagner un contrôle incomplet.
Les catégories numériques sont low (0–19), medium (20–39), elevated (40–59), high (60–79) et critical (80–100). Un résultat low n’autorise pas à laisser passer un paiement. En particulier, les drapeaux d’indisponibilité d’un registre SEPA ou VoP ne majorent pas le score : il faut les lire séparément. La réponse sert à documenter une revue, pas à remplacer les contrôles du compte ou du bénéficiaire.
Portée et provenance
finma_register se rattache par identifiants seulement (IID, BIC, LEI, IDE), jamais par un nom. Il lit une copie datée, collectée par OpenSwissData : ce n’est pas un service de la FINMA, à vérifier sur finma.ch avant toute décision. Une copie de plus de 14 jours répond not_verified. Le fichier ne donne ni date d’autorisation ni statut : le champ n’en indique donc aucun. Il couvre les IBAN suisses sur cette route, pas le contrôle direct par BIC.
La comparaison bancaire utilise normalement le BIC8 exact. Pour une banque russe, les BIC SWIFT par défaut des lignes de sa licence sont comparés sur leurs six premiers caractères. Les BIC secondaires ne sont pas comparés. Si aucun BIC exploitable n’est disponible, l’axe banque reste non contrôlé ; une désignation sans BIC ou sous un autre préfixe peut échapper à cette recherche.
Champ dans meta | Lecture |
|---|---|
scope, disclaimer | bank_bic_only et la limitation textuelle ; les conserver avec le rapport. |
sources | Sources chargées, chaîne séparée par des virgules, ou null ; ce n’est pas la preuve que chaque axe a été consulté pour cet appel. |
sanctions_as_of | Date de rafraîchissement des données de conformité, ou null ; ne garantit pas la fraîcheur uniforme de chaque liste. |
fatf_as_of | Mois de la plénière représentée, ou null. |
country_risk_as_of, country_risk_scope | Date et explication de l’axe éditorial pays, distinct du statut GAFI. |
Le calendrier de rafraîchissement ne remplace pas ces dates servies. Conserver également les crédits de source et l’éventuel bloc attribution du chemin IBAN. La présence d’une banque dans le registre VoP ne déclenche pas une requête de vérification du bénéficiaire : voir notre guide VoP et la présentation du dispositif par l’EPC.
Erreurs et étape suivante
| Statut / code | Signification |
|---|---|
400 invalid_json | JSON mal formé. |
400 invalid_request | Aucun IBAN/BIC textuel non vide, ou deux valeurs non vides à la fois. |
400 invalid_bic_format | BIC fourni hors format attendu. |
| 402 | Accès ou unités insuffisants ; examiner le corps du refus. |
| 429 | Attendre Retry-After ; ce n’est pas le quota mensuel. |
Ne pas convertir un échec HTTP ou une source indisponible en « aucun risque ». Voir la référence des erreurs, les recettes, la prise en main et les sources de données.