Schweizer Clearing: IID oder QR-IID abfragen
GET /v1/ch/clearing/:iid fragt eine SIX-BankMaster-Referenz eines Schweizer oder liechtensteinischen Instituts ab. Die Antwort enthält verfügbare Bankdaten, den BIC und Angaben zur Teilnahme an Zahlungssystemen. Sie bestätigt weder ein Konto noch dessen Inhaber und garantiert keine Zahlungsannahme.
Dokumentation geprüft am 4. November 2026. Bankdaten können sich ändern: die aktuelle Antwort lesen, statt eine frühere Momentaufnahme in der Integration festzuschreiben.
Erster Aufruf mit einem wiederverwendbaren Schlüssel
Einen API-Schlüssel erstellen oder abrufen und IBANFORGE_API_KEY in der Umgebung des Programms setzen. Für weitere Aufrufe denselben Schlüssel behalten; nicht in öffentlich ausgelieferten Seitencode einbauen.
curl --fail-with-body -sS https://api.ibanforge.com/v1/ch/clearing/230 \
-H "X-API-Key: ${IBANFORGE_API_KEY}"X-API-Key akzeptiert einen Schlüssel ifk_…; Authorization: Bearer ifk_… wird ebenfalls unterstützt. Kontingent und Kosten richten sich nach dem Zugang auf der Preisseite. x402 ist eine weitere Zugangsmöglichkeit, keine Voraussetzung. Der REST-Test ohne Schlüssel für einzelne IBAN-Prüfungen gilt nicht für diese Clearing-Route.
Welcher Identifikator wird übergeben?
| Eingabe | Behandlung |
|---|---|
| Eine bis fünf Ziffern | Links auf fünf Stellen ergänzt: 230 wird zu 00230. |
QR-IID von 30000 bis 31999 | Die Abfrage akzeptiert die QR-Nummer direkt; daraus keine gewöhnliche IID berechnen. |
| Alte IID mit Weiterleitung in der verwendeten Tabelle | Die Antwort kann den Nachfolger nennen und redirected_from ergänzen. Die angefragte Nummer zur Prüfung behalten. |
Eine zulässige Schreibweise belegt keinen Eintrag in den Daten. Der QR-Bereich kennzeichnet einen Identifikatortyp, nicht ein Institut für jede Nummer.
Felder innerhalb ihres Aussagebereichs lesen
| Feld | Bedeutung |
|---|---|
found | Eine Referenz wurde in den abgefragten Daten gefunden. |
iid | IID des ermittelten Instituts. Ist einer QR-Zeile eine gewöhnliche IID zugeordnet, wird diese ausgegeben. Fehlt die Zuordnung, behält die API die IID der Zeile bei, statt eine zu erfinden. |
institution, address, bic | Verfügbares Institut, Bankadresse und BIC. Die Adresse gehört nicht dem Zahlungsempfänger. |
payment_services | Angaben der Zeile zu sic, rtgs_chf, instant_payments_chf, eurosic, lsv_bdd_chf und lsv_bdd_eur. Das sind keine Live-Prüfungen der Verfügbarkeit eines Kontos. |
sic_iid | Teilnehmernummer der abgefragten SIX-Zeile. Bei einer QR-Abfrage kann sie von der Nummer der gewöhnlichen IID-Zeile abweichen. |
qr_iid | Verfügbare QR-Nummer, auch bei manchen Abfragen gewöhnlicher IIDs; null, wenn keine ermittelt wird. |
qr_iid_source | register: Zuordnung aus Registerzeilen; headquarters: vom Hauptsitz übernommen; null: keine Zuordnung ermittelt. |
qr_iids | Liste, wenn mehrere QR-IIDs ermittelt werden. Das einzelne Feld behält die kleinste; wer nur dieses liest, verliert die anderen Werte. |
is_qr_iid | true, wenn die abgefragte Zeile eine QR-IID ist. Ein vorhandenes qr_iid allein bedeutet nicht, dass eine QR-Nummer angefragt wurde. |
valid_on | Gültigkeitsdatum der SIX-Zeile. Weder Datum des letzten Downloads noch Zusicherung der Aktualität. |
redirected_from, note | Optionale Weiterleitung und Erläuterung. Lieferantenbankdaten nicht automatisch ersetzen. |
Bei einer Kantonalbank kann die Antwort zusätzlich state_guarantee mit eigener Quelle enthalten. Diese separate Angabe bestätigt kein Konto und keine Zahlung.
Fehlendes Ergebnis und Fehler
Nach einem autorisierten Aufruf ist HTTP 200 mit found: false und error: "clearing_not_found" ein Suchergebnis. Die verwendeten Daten liefern keine Referenz; daraus folgt weder ein geschlossenes Konto noch zwingend ein nicht mehr bestehendes Institut.
Zuerst den HTTP-Status lesen, danach das fachliche Ergebnis. Für ein falsches IID-Format hat die Route eine 400-Antwort; Zugangskontrollen können bereits vor der Suche antworten. 402 wegen nicht abgedeckten Zugangs bedeutet keine fehlende IID. Weitere Fälle stehen unter Limits und Fehler.
Von einer IBAN oder QR-Rechnung ausgehen
Die IBAN-Prüfung kann für CH/LI einen Block clearing enthalten, wenn eine Referenz ermittelt wird. Diesen Weg nutzen, wenn die vollständige IBAN bereits vorliegt.
Eine QR-Rechnung kann je nach Referenz eine gewöhnliche IBAN oder eine QR-IBAN verwenden. Der QR-IBAN-Leitfaden trennt Nummernerkennung, Bankabfrage und Prüfung des Swiss-QR-Code-Texts. Aus einer zurückgegebenen IID niemals die QR-IBAN eines Kunden konstruieren.