Clearing suisse : chercher un IID ou un QR-IID
GET /v1/ch/clearing/:iid consulte la référence SIX BankMaster d’un établissement suisse ou liechtensteinois. Il renvoie les données disponibles de la banque, son BIC et les indicateurs de participation aux systèmes de paiement. Il ne vérifie ni un compte ni son titulaire, et ne garantit pas l’acceptation d’un paiement.
Documentation relue le 4 novembre 2026. Les valeurs d’une banque peuvent changer : lire la réponse actuelle plutôt que figer une capture dans une intégration.
Premier appel avec une clé conservée
Créer ou retrouver une clé API, puis définir IBANFORGE_API_KEY dans l’environnement du programme. Conserver la même clé pour les appels suivants ; ne pas l’intégrer au code d’une page publique.
curl --fail-with-body -sS https://api.ibanforge.com/v1/ch/clearing/230 \
-H "X-API-Key: ${IBANFORGE_API_KEY}"X-API-Key accepte une clé ifk_… ; Authorization: Bearer ifk_… est aussi reconnu. L’allocation et le coût dépendent de l’accès choisi, décrit dans les tarifs. x402 est une autre voie d’accès, pas une obligation. L’essai REST sans clé de validation unitaire ne s’étend pas à cette route clearing.
Quel identifiant envoyer ?
| Entrée | Traitement |
|---|---|
| De un à cinq chiffres | L’identifiant est complété à gauche sur cinq chiffres : 230 devient 00230. |
QR-IID entre 30000 et 31999 | La recherche accepte directement le numéro QR ; ne pas en déduire un IID ordinaire par calcul. |
| Ancien IID redirigé dans la table servie | La réponse peut nommer son successeur et ajouter redirected_from. Conserver l’identifiant demandé pour la revue. |
Une syntaxe recevable ne prouve pas que l’identifiant figure dans les données. La plage QR décrit un type d’identifiant, pas l’existence d’un établissement à chaque numéro.
Lire les champs sans élargir leur portée
| Champ | Lecture |
|---|---|
found | Présence d’une référence dans les données consultées. |
iid | IID de l’établissement résolu. Pour une ligne QR associée à un IID ordinaire, ce dernier est renvoyé. Si la ligne n’a pas cette association, l’API conserve son IID au lieu d’en inventer un. |
institution, address, bic | Institution, adresse de la banque et BIC disponibles. L’adresse n’est pas celle du bénéficiaire. |
payment_services | Indicateurs sic, rtgs_chf, instant_payments_chf, eurosic, lsv_bdd_chf et lsv_bdd_eur de la ligne consultée. Ce ne sont pas des tests de disponibilité instantanée d’un compte. |
sic_iid | Numéro participant de la ligne SIX consultée. Sur une recherche QR, il peut être différent de celui de la ligne de l’IID ordinaire. |
qr_iid | Identifiant QR disponible, y compris sur certaines recherches d’IID ordinaires ; null quand aucun n’est résolu. |
qr_iid_source | register : association issue des lignes du registre ; headquarters : héritée du siège ; null : aucune association résolue. |
qr_iids | Liste ajoutée lorsque plusieurs QR-IID sont résolus. Le champ singulier conserve le plus petit ; ne pas perdre les autres en lisant seulement celui-ci. |
is_qr_iid | true lorsque la ligne recherchée est un QR-IID. La seule présence de qr_iid ne signifie pas que la requête portait sur un numéro QR. |
valid_on | Date de validité de la ligne SIX. Ce champ n’est ni la date du dernier téléchargement ni une promesse de fraîcheur. |
redirected_from, note | Redirection et explication éventuelles. Ne pas remplacer automatiquement les coordonnées d’un fournisseur. |
Une réponse d’une banque cantonale peut aussi inclure state_guarantee, avec sa propre source. Ce renseignement distinct ne valide pas un compte ni un paiement.
Résultat absent et erreurs
Après un appel autorisé, HTTP 200 avec found: false et error: "clearing_not_found" est un résultat de recherche. Il signifie que les données servies n’ont pas fourni cette référence, pas que le compte est fermé ou que l’établissement a forcément disparu.
Lire le code HTTP avant le corps métier. Le format IID invalide a une réponse 400 dans la route ; les contrôles d’accès peuvent répondre avant la recherche. Une réponse 402 d’accès non couvert n’est pas un IID absent. Les limites et erreurs décrivent les autres cas.
Partir d’un IBAN ou d’une QR-facture
La validation IBAN peut inclure le bloc clearing pour CH/LI lorsqu’une référence est résolue. Utiliser cette voie si l’IBAN complet est déjà disponible.
Une QR-facture peut utiliser un IBAN ordinaire ou un QR-IBAN, selon sa référence. Le guide QR-IBAN sépare reconnaissance du numéro, recherche bancaire et contrôle du texte Swiss QR Code. Ne jamais fabriquer un QR-IBAN de client à partir d’un IID retourné.