API zur Prüfung Schweizer QR-IBANs — eine QR-IID auflösen

Eine Schweizer QR-Rechnung trägt eine QR-IBAN, und eine QR-IBAN ist keine gewöhnliche Schweizer IBAN unter anderem Namen. Sie identifiziert ihr Institut über einen eigenen Nummernkreis, den von SIX für die QR-Rechnung reservierten QR-IID-Bereich 30000–31999. Dasselbe Institut hört damit auf zwei Kennungen gleichzeitig — und die eine für die andere zu halten ist der häufigste Weg, eine völlig korrekte Zahlungsverbindung zurückzuweisen.

Diese Seite ist die Referenz für die drei Fragen, die daraus folgen: wie man eine QR-IBAN erkennt, wie man ihre QR-IID zu einem benannten Institut auflöst und was eine CH/LI-Validierung ungefragt mitliefert. Alle Antworten unten stammen aus den ausgelieferten SIX-BankMaster-Daten, keine ist von Hand geschrieben.

Ein Institut, zwei Kennungen

Die Stellen 5–9 einer Schweizer IBAN tragen die Institutsidentifikation (IID, auch BC-Nummer genannt). Für QR-Rechnungen mit QR-Referenz vergibt SIX dem Institut eine zweite Kennung aus dem reservierten Bereich — und die beiden Zahlen haben nichts miteinander zu tun, weder rechnerisch noch als Präfix:

Drei Folgen, in der Reihenfolge, in der sie zubeißen:

1. Eine QR-IID, die man in einer BC-Nummern-Tabelle nachschlägt, liefert nichts. Wer daraus schließt, die QR-IBAN sei fehlerhaft, verwirft eine korrekte Anweisung — der verbreitetste Ausfall in Schweizer Zahlungsintegrationen.
2. Über die Referenzart entscheidet der Nummernkreis, nicht die Rechnung. Eine IBAN, deren IID zwischen 30000 und 31999 liegt, verlangt eine strukturierte QR-Referenz; eine gewöhnliche IBAN nimmt eine Creditor Reference oder einen freien Mitteilungstext. Vertauscht man beides, wird die Anweisung bei der Einreichung abgewiesen.
3. Ein Institut kann mehrere QR-IIDs halten. UBS hält zwei. Code, der von einem einzigen Wert ausgeht, schneidet die Menge stillschweigend ab.

Von den 1,100+ Schweizer Clearing-Einträgen, die wir aus dem SIX BankMaster ausliefern, liegen 231 im QR-Bereich, davon 224 mit BIC — gemessen auf dem Refresh 2026-08; die Zahl bewegt sich mit Fusionen und geänderter Teilnahme. Eine Kennung aus dem QR-Bereich ohne Institut dahinter ist eine echte Antwort und kein Fehler: die API sagt found: false.

Schritt 1 — die QR-IBAN erkennen (kostenlos)

GET /v1/iban/format zerlegt eine IBAN, ohne irgendetwas nachzuschlagen, und kostet nichts:

curl "https://api.ibanforge.com/v1/iban/format?iban=CH5530024123000889012"

{
  "iban": "CH5530024123000889012",
  "formatted": "CH55 3002 4123 0008 8901 2",
  "valid": true,
  "check_digits": "55",
  "country": { "code": "CH", "name": "Switzerland" },
  "bban": { "bank_code": "30024", "account_number": "123000889012" },
  "upgrade_to_full_validation": "POST /v1/iban/validate ($0.005) — adds BIC, SEPA, VoP, sanctions, Swiss BC-Nummer."
}

bank_code ist 30024: im Bereich, also eine QR-IBAN. Die Prüfziffer stimmt, die Struktur stimmt — und Sie wissen weiterhin nicht, welches Institut sie ausgegeben hat. Dafür braucht es ein Register.

Schritt 2 — QR-IID-Lookup (GET /v1/ch/clearing/:iid)

Der Clearing-Endpoint nimmt eine QR-IID direkt entgegen und übersetzt zwischen den beiden Nummernkreisen:

curl https://api.ibanforge.com/v1/ch/clearing/30024 \
  -H "Authorization: Bearer ifk_live_xxxxxxxxxxxxxxxxxxxx"

{
  "iid": "06300",
  "found": true,
  "institution": {
    "name": "Valiant Bank AG",
    "type": "bank",
    "iid_type": "other",
    "headquarters_iid": "06300"
  },
  "address": {
    "street": "Bundesplatz",
    "building_number": "4",
    "post_code": "3001",
    "town": "Bern",
    "country": "CH"
  },
  "bic": "VABECH22XXX",
  "payment_services": {
    "sic": true,
    "rtgs_chf": true,
    "instant_payments_chf": true,
    "eurosic": true,
    "lsv_bdd_chf": false,
    "lsv_bdd_eur": false
  },
  "sic_iid": "300240",
  "qr_iid": "30024",
  "qr_iid_source": "register",
  "valid_on": "2026-08-03",
  "cost_usdc": 0.003,
  "processing_ms": 0.06,
  "is_qr_iid": true,
  "note": "IID 30024 is a QR-IID (QR-bill range 30000–31999) of Valiant Bank AG; the institution's standard IID is 06300."
}

Lesen Sie die ersten Felder genau — ihre Semantik ist Absicht:

Preis. 0,003 $ pro Aufruf per x402, oder eine Einheit des kostenlosen Kontingents mit einem API-Key. Die obige Aufzeichnung ist ein nicht authentifizierter, per x402 bepreister Aufruf — daher cost_usdc: 0.003; mit einem Key innerhalb seines Monatskontingents kommt dasselbe Feld als 0 zurück.

Eine Kennung aus dem QR-Bereich, die SIX nicht führt, liefert found: false mit error: "clearing_not_found" und HTTP 200 — ein Rechercheergebnis, kein Fehlschlag.

Die Gegenrichtung — welche QR-IID hält diese Bank?

SIX veröffentlicht die Zuordnung nur in eine Richtung: die QR-Zeile nennt das Institut, keine gewöhnliche Zeile nennt ihre QR-IID. Wir indexieren sie rückwärts, sodass auch eine gewöhnliche Schweizer IBAN die Frage beantwortet — jene Frage, die ein Unternehmen tatsächlich stellt, wenn es mit QR-Rechnungen beginnt. Hier der clearing-Block zur gewöhnlichen UBS-IBAN CH1000230000000012345:

{
  "iid": "00230",
  "name": "UBS Switzerland AG",
  "type": "bank",
  "town": "Zürich",
  "sic": true,
  "instant_payments_chf": true,
  "eurosic": true,
  "qr_iid": "30005",
  "qr_iid_source": "register",
  "qr_iids": ["30005", "30308"]
}

Zwei Felder tragen die Redlichkeit dieser Antwort:

• qr_iids erscheint, wenn SIX demselben Institut mehr als eine QR-IID zugeteilt hat. Der Skalar qr_iid behält die kleinste, damit Code, der nur dieses Feld liest, weiterhin einen veröffentlichten Wert erhält statt einer stillen Kürzung.
• qr_iid_source trennt zwei unterschiedlich starke Aussagen. register ist eine von SIX veröffentlichte Zuordnung. headquarters heißt, die Zeile ist eine Niederlassung und die QR-IID gehört ihrem Hauptsitz — eine Ableitung, tragfähig, weil SIX pro Institut zuteilt, aber eben eine Ableitung. Beides unetikettiert auszuliefern hielte sie am gleichen Maßstab, den sie nicht verdienen.

Schritt 3 — die QR-IBAN vollständig validieren (POST /v1/iban/validate)

Für CH und LI trägt ein einziger Validierungsaufruf den Clearing-Block inline mit. Keine zweite Anfrage, kein eigenhändiges Herausschneiden der Stellen 5–9:

curl -X POST https://api.ibanforge.com/v1/iban/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ifk_live_xxxxxxxxxxxxxxxxxxxx" \
  -d '{"iban": "CH5530024123000889012"}'

{
  "iban": "CH5530024123000889012",
  "valid": true,
  "country": { "code": "CH", "name": "Switzerland" },
  "check_digits": "55",
  "bban": { "bank_code": "30024", "account_number": "123000889012" },
  "sepa": { "member": true, "schemes": ["SCT", "SDD"], "vop_required": false, "vop_participant": false },
  "formatted": "CH55 3002 4123 0008 8901 2",
  "bic": {
    "code": "VABECH22",
    "bank_name": "Valiant Bank AG",
    "city": "Bern",
    "source": "IBANforge curated bank-code map",
    "as_of": "2026-08",
    "lei": "529900Z7NMGN5XV0RV34",
    "lei_status": "ACTIVE"
  },
  "issuer": { "type": "bank", "name": "Valiant Bank AG", "classification": "default" },
  "risk_indicators": {
    "issuer_type": "bank",
    "country_risk": "standard",
    "test_bic": false,
    "sepa_reachable": true,
    "sepa_reachable_scope": "country",
    "vop_coverage": false
  },
  "bank_code_check": {
    "value": "30024",
    "status": "verified",
    "match": "register",
    "register": "SIX BankMaster (Swiss IID / BC-Nummer register)",
    "authoritative": true,
    "institution": {
      "name": "Valiant Bank AG",
      "street": "Bundesplatz 4",
      "post_code": "3001",
      "town": "Bern",
      "country": "CH"
    },
    "as_of": "2026-08"
  },
  "clearing": {
    "iid": "06300",
    "name": "Valiant Bank AG",
    "type": "bank",
    "town": "Bern",
    "sic": true,
    "instant_payments_chf": true,
    "eurosic": true,
    "qr_iid": "30024",
    "qr_iid_source": "register",
    "is_qr_iid": true
  },
  "cost_usdc": 0.005,
  "processing_ms": 0.53
}

(Der GLEIF-Block bic.address und das Array next_steps sind oben aus Platzgründen weggelassen; beide sind in der echten Antwort enthalten.)

bank_code_check.authoritative: true sagt, dass das Urteil von der Vergabestelle selbst kommt — dem SIX BankMaster, nicht einem BIC-Verzeichnis, das nebenbei Schweizer Banken führt. is_qr_iid: true innerhalb von clearing markiert die IBAN als QR-IBAN, während iid bereits die gewöhnliche Nummer des Instituts trägt.

Schritt 4 — Referenz und Konto zusammenführen (reference_check)

Eine QR-IBAN zu erkennen ist nur die halbe Arbeit. Die andere Hälfte ist die daneben gedruckte Referenz, und die Swiss Payment Standards machen beide untrennbar:

Eine QRR-Referenz (die strukturierte QR-Referenz) darf nur in Kombination mit einer QR-IBAN verwendet werden. Eine ISO-11649-Creditor-Reference — in den Swiss Payment Standards SCOR — darf nicht zusammen mit einer QR-IBAN verwendet werden.

— SIX, Swiss Implementation Guidelines Credit Transfer (pain.001), SPS 2026 v2.3, Dokument vom 20.02.2026, gültig ab 14. November 2026; und SIX, Swiss Implementation Guidelines for the QR-bill v2.4 § 4.3.2: „Use of the Creditor Reference (ISO 11649) presupposes that an IBAN has been used. A QR-IBAN cannot be used."

Die Guidelines kennzeichnen Verstösse gegen diese Regel mit den Fehlercodes CH16 und CH17. Wir nennen die Codes, weil sie in der Spalte der Guidelines selbst stehen; wir zitieren ihren Wortlaut nicht, denn dieser lebt in einem Status-Report-Dokument, das wir nicht gelesen haben. Die Antwort verweist deshalb auf „the Swiss Implementation Guidelines (SPS)" und hört dort auf.

Übergeben Sie POST /v1/iban/validate eine reference, und die Antwort erhält einen Block reference_check mit zwei unabhängigen Urteilen:

Die beiden bewegen sich nicht gemeinsam. Eine Referenz kann arithmetisch einwandfrei und auf dieser IBAN dennoch unzulässig sein — genau der Fall, für den die Regel existiert.

Die vier Ausgänge der Zuordnung

Eine QR-Referenz auf der QR-IBAN, zu der sie gehört:

curl -X POST https://api.ibanforge.com/v1/iban/validate \
  -H "Content-Type: application/json" \
  -d '{"iban":"CH4431999123000889012","reference":"210000000003139471430009017"}'

{
  "reference_check": {
    "reference": "210000000003139471430009017",
    "scheme": "qrr",
    "valid": true,
    "status": "checked",
    "check_digit_expected": "7",
    "source": "SIX Swiss Implementation Guidelines for the QR-bill v2.4 (document dated 24.02.2026, valid from 14 November 2026), Annex B \"Check digit calculation by modulo 10 recursive\".",
    "as_of": "2026-02",
    "pairing": "ok",
    "pairing_as_of": "2026-02"
  }
}

Dieselbe Referenz auf einer gewöhnlichen Schweizer IBAN — der Fehler, für dessen Abfangen dieser Block existiert:

{
  "reference_check": {
    "scheme": "qrr",
    "valid": true,
    "pairing": "qrr_requires_qr_iban",
    "note": "… Pairing: IID 04835 is outside the SIX QR range 30000–31999, so this is an ordinary IBAN, and a QRR reference may only be used in combination with a QR-IBAN per the Swiss Implementation Guidelines (SPS). Either use the creditor's QR-IBAN or send this payment without a QRR reference."
  }
}

valid steht weiterhin auf true. Die Referenz ist in Ordnung; die Kombination ist es nicht. Code, der nur valid liest, schickt diese Instruktion los und bekommt sie bei der Einreichung zurückgewiesen.

Ausserhalb der Schweiz und Liechtensteins lautet pairing not_applicable — es gibt keine QR-IBAN, gegen die zugeordnet werden könnte, und ok zu melden würde eine nie durchgeführte Prüfung behaupten. Das Prüfziffernurteil der Referenz selbst bleibt davon unberührt: eine gültige RF-Referenz ist überall gültig.

Die Referenz-Prüfziffern allein sind kostenlos

Die Arithmetik ist eine veröffentlichte Commodity und kostet daher nichts:

curl "https://api.ibanforge.com/v1/reference/validate?reference=RF18539007547034"

{
  "reference": "RF18539007547034",
  "scheme": "rf",
  "valid": true,
  "status": "checked",
  "check_digit_expected": "18",
  "source": "Finance Finland, \"Structure of the RF Creditor Reference (ISO 11649)\", October 2023 (check-digit algorithm); SIX Swiss Implementation Guidelines for the QR-bill v2.4 § 2.12.2, valid from 14 November 2026 (structure).",
  "as_of": "2023-10"
}

Vier Schemata werden arithmetisch geprüft, jedes gegen ein Primärdokument, das die Regel kostenfrei veröffentlicht:

Die norwegische KID und die schwedische OCR werden erkannt, nie beurteilt. Sie antworten mit valid: null und status: "unverifiable_without_creditor_config", denn Modulus-Typ und zulässige Länge werden pro Gläubigerkonto von der Bank des Begünstigten konfiguriert und sind keine Eigenschaft der Zeichenkette. Ein false würde einwandfreie Referenzen zurückweisen, also tun wir das nicht. Geben Sie ein null niemals als „ungültig" an Nutzer weiter — geben Sie weiter, dass die Prüfung die Konfiguration der Gläubigerbank benötigt.

Eine Mehrdeutigkeit sollte man kennen. Nur ein führendes RF und eine Länge von 27 Ziffern legen ein Schema eindeutig fest. Eine blosse zwölfstellige Ziffernfolge ist zugleich eine belgische OGM und eine zulässige finnische Länge: Die Antwort liefert daher die spezifischere Lesart und meldet die andere in also_valid_as. Übergeben Sie reference_type, wenn Sie das Land kennen.

Klassifikation virtueller IBANs und Identifizierung der Endnutzer (AMLR Art. 22(3))

Derselbe issuer-Block, der für Valiant bank zeigt, markiert andernorts einen Emittenten virtueller IBANs. Das reicht über die Schweiz hinaus, wegen einer bestimmten europäischen Pflicht.

Was die Verordnung sagt. Artikel 22(3) der Verordnung (EU) 2024/1624 — der AMLR, anwendbar ab dem 10. Juli 2027 — verpflichtet Kredit- und Finanzinstitute, die Informationen zu erheben, mit denen die natürlichen oder juristischen Personen identifiziert und deren Identität überprüft wird, die eine von ihnen ausgegebene virtuelle IBAN nutzen, samt dem zugehörigen Bank- oder Zahlungskonto. Das Institut, das das Konto führt, auf das eine vIBAN weiterleitet, muss diese Information vom ausgebenden Institut unverzüglich erhalten können, in jedem Fall innerhalb von fünf Arbeitstagen nach seiner Anfrage.

Was daraus operativ folgt. Beide Seiten einer vIBAN-Konstruktion müssen wissen, wer die Kennung ausgegeben hat, die sie in Händen halten, bevor sie handeln können. Nichts in diesem Artikel macht eine IBAN-Validierungs-API zur Adressatin dieser Pflicht — und nichts hier ist Rechtsberatung —, aber der erste, rein tatsächliche Schritt ist ein Klassifikationsproblem: welches Institut steht hinter dieser IBAN, und von welcher Art ist es?

Was unsere API dazu beiträgt. issuer.type ist ein strukturelles Signal, und issuer.classification sagt, was es wert ist:

Dieselbe Klassifikation speist den Risikoscore von POST /v1/iban/compliance: ein emi-Emittent bringt 10 Punkte und das Flag emi_issuer, ein payment_institution 15 Punkte mit dem Flag payment_institution_issuer. Hier die beiden Blöcke, die dieser Aufruf zusätzlich zur obigen Validierung liefert, aufgezeichnet an derselben Schweizer QR-IBAN:

{
  "compliance": {
    "sanctions": {
      "country_sanctioned": false,
      "bank_sanctioned": false,
      "matched_lists": [],
      "fatf_status": "member",
      "bank_screened": true
    },
    "reachability": { "sepa_instant": false, "sct": true, "sdd": false, "screened": true },
    "vop": { "participant": false, "status": "not_found", "screened": true },
    "risk_score": 10,
    "risk_level": "low",
    "flags": ["no_sepa_instant", "no_vop"]
  },
  "meta": {
    "scope": "bank_bic_only",
    "disclaimer": "Informational triage only — NOT a regulated AML/CFT product. Sanctions screening is performed at the BANK (BIC8) level: it flags the holding institution, NOT the beneficiary / account-holder name. Most sanctions designations target persons and companies, which this does not screen. Use a regulated provider (Refinitiv, ComplyAdvantage, etc.) for name-level KYC/AML obligations.",
    "sanctions_as_of": "2026-08-24T15:52:44.509Z",
    "fatf_as_of": "2026-06",
    "sources": "EU,OFAC,UN,FATF,EPC-SCT,EPC-SCT_INST,EPC-SDD"
  }
}

Dieser meta.disclaimer ist keine Zierde und wird hier nicht abgeschwächt: Es handelt sich um informative Vorsortierung, nicht um ein reguliertes AML/CFT-Produkt. Das Sanktionsscreening läuft auf Bankebene (BIC8) gegen OFAC-, EU- und UN-Daten — es markiert das führende Institut, nie den Namen des Begünstigten oder Kontoinhabers. Es ist ein vorgelagertes Signal darüber, welche Art von Institut hinter einer Kennung steht; die Identifizierung der Endnutzer nach Art. 22(3) geschieht beim ausgebenden Institut, mit Mitteln, die wir weder besitzen noch ersetzen.

Schritt 5 — die ganze QR-Rechnung prüfen (POST /v1/ch/qr-bill/check, kostenlos)

Der Text in einem Swiss QR Code (der «Swiss Payments Code», 31 positionsgebundene Zeilen von SPC bis EPD) lässt sich in einem Aufruf prüfen: Kopfzeilen und Version, Kreditoren-IBAN und ihre Zugehörigkeit zum QR-IID-Bereich, die Referenz QRR / SCOR / NON mit Prüfziffer, die Paarungsregeln (eine QR-IBAN verlangt QRR; eine gewöhnliche IBAN verbietet sie), Betrag und Währung, leer gelassener endgültiger Kreditor, und das, was die SIX-Frist vom 14. November 2026 dringend macht: Sind die Adressen von Kreditor und endgültigem Debitor strukturiert (Typ S) oder noch kombiniert (Typ K)?

curl -s -X POST https://api.ibanforge.com/v1/ch/qr-bill/check \
  -H "Content-Type: application/json" \
  -d '{ "payload": "SPC\n0200\n1\nCH4431999123000889012\nS\nRobert Schneider AG\nRue du Lac\n1268\n2501\nBiel\nCH\n\n\n\n\n\n\n\n1949.75\nCHF\nS\nPia Rutschmann\nMarktgasse\n28\n9400\nRorschach\nCH\nQRR\n210000000003139471430009017\nOrder 15.06.2026\nEPD" }'

Die Antwort trägt valid (kein Befund der Stufe error), ready_for_2026_11_14 (gültig und jede vorhandene Adresse ist Typ S), je einen findings-Eintrag pro verletzter Regel mit source, und für eine kombinierte Adresse einen Block proposed_structured: die aus den beiden kombinierten Zeilen abgeleiteten S-Felder, als Korrektur weiterzugeben. Adressen vom Typ K wurden am 21. November 2025 aus dem Standard entfernt; ab dem 14. November 2026 verarbeiten die Banken darauf beruhende Daueraufträge und Zahlungsvorlagen nicht mehr.

Kostenlos, reine Regelprüfung, ohne Datenbank: die Bank hinter der IBAN und ihre Teilnahme an den Zahlungsschienen bleiben Sache von POST /v1/iban/validate. Dieselbe Prüfung ist das MCP-Tool check_swiss_qr_bill und die Seite /tools/qr-bill.

Die Grenzen, offen gesagt

• Das Institut, nie das Konto oder dessen Inhaber. Eine aufgelöste QR-IID benennt das ausgebende Institut. Über die zwölf Ziffern, die ihr in der IBAN folgen, und über die Person dahinter sagt sie nichts.
• Die Referenzart ist eine Regel, keine Vorhersage. Wir sagen Ihnen, dass eine IBAN im QR-Bereich liegt und deshalb eine strukturierte QR-Referenz verlangt. Ob eine konkrete Anweisung nachgelagert angenommen wird, hängt von der Bank des Schuldners und von der Referenz selbst ab.
• Eine Referenz-Prüfziffer beweist nicht, dass es die richtige Referenz ist. valid: true sagt, dass die Ziffern in sich stimmig sind; es sagt nichts darüber, ob diese Referenz zu der Rechnung passt, die der Gläubiger auszugleichen erwartet.
• Zwei Schemata, die wir bewusst nicht beurteilen. Die norwegische KID und die schwedische OCR werden pro Gläubigerkonto von der Bank des Begünstigten konfiguriert. Wir erkennen das Format und hören dort auf, statt ein Urteil zu erfinden, das wir nicht belegen können.
• CH16 / CH17 werden genannt, nie zitiert. Die Codes stehen in den Guidelines; ihr Wortlaut lebt in einem Status-Report-Dokument, das wir nicht konsultiert haben.
• Monatliche Aktualität, immer datiert. Der SIX BankMaster wird monatlich erneuert, und jede Clearing-Antwort trägt ihr valid_on. Eine QR-IID, die vor einem Jahr galt, kann heute umgeleitet sein.
• qr_iid_source: "headquarters" ist eine Ableitung. Tragfähig, etikettiert und nie als veröffentlichte SIX-Zuordnung ausgegeben.

Weiter geht es hier

• Schweizer Clearing (BC-Nummer) — die vollständige Endpoint-Referenz, Teilnahme an den Systemen, Semantik von found: false
• IBAN validieren — der komplette Antwortvertrag, inklusive issuer und bank_code_check
• Compliance-Prüfung — Sanktionen, FATF, VoP und der Risikoscore 0–100
• Datenquellen und Provenienz — welches Register für welches Land antwortet und was eine Fehlanzeige bedeutet
• Eine QR-IID auflösen: welches Institut steckt hinter einer Schweizer QR-IBAN? — die erzählende Fassung, mit den praktischen Ausfällen