API-Dokumentation

Ergebnis-Codes und Fehlerbehandlung

Prüfen Sie HTTP-Status und JSON-Antwort gemeinsam. Auch bei HTTP 200 können Fehler oder negative Prüfergebnisse im Body stehen. error: false allein bestätigt keine gültigen Bankdaten. Werten Sie code aus; der übersetzbare Text in message dient nur der Anzeige.

Bei einer einzelnen IBAN-Prüfung steht 2100 für eine gültige IBAN, 2200 für eine erfolgreiche Generierung und 2500 für ein gültiges BIC-Format. Bei der deutschen Bankkontoprüfung bedeutet 2300 nur „Prüfung durchgeführt“: Zusätzlich bank.valid und konto.valid auswerten.

Bei HTTP 401 die Authentifizierung korrigieren. Bei HTTP 429 einen vorhandenen Retry-After-Header beachten. Bei HTTP 5xx oder Netzwerkfehlern nur begrenzt mit wachsender Wartezeit wiederholen. Eine HTML-Fehlerseite oder fehlende JSON-Antwort ist kein Validierungsergebnis.

SEPA: Lastschriften, Überweisungen und Echtzeitüberweisungen

Bei der IBAN-Prüfung erhalten Sie zusätzlich die Teilnahme der Bank an vier SEPA-Verfahren. Der Abgleich erfolgt anhand der EPC-Teilnehmerregister.

• details.sepa.sddCore – SEPA-Basislastschrift (Core)
• details.sepa.sddB2b – SEPA-Firmenlastschrift (B2B)
• details.sepa.sct – SEPA-Überweisung (SCT)
• details.sepa.sctInst – SEPA-Echtzeitüberweisung (SCT Inst)

Alle vier Verfahren werden unabhängig geprüft. confirmed bestätigt eine eindeutige, aktuelle Registerzuordnung. unknown bedeutet, dass die Teilnahme nicht bestätigt werden konnte – nicht, dass die Bank das Verfahren nicht unterstützt.

Pro Verfahren enthält die Antwort nur status und reason. Der SEPA-Status ändert das Ergebnis der IBAN-Prüfung nicht.

Beispiel: Ausschnitt aus einer IBAN-Prüfantwort

{
  "details": {
    "sepa": {
      "sddCore": {
        "status": "confirmed",
        "reason": "matched"
      },
      "sddB2b": {
        "status": "confirmed",
        "reason": "matched"
      },
      "sct": {
        "status": "confirmed",
        "reason": "matched"
      },
      "sctInst": {
        "status": "confirmed",
        "reason": "matched"
      }
    }
  }
}

Bedeutung von reason

• matched – Teilnahme bestätigt
• no_data – Keine Registerdaten verfügbar
• missing_bic – Keine BIC verfügbar
• ambiguous_bank – Bankzuordnung nicht eindeutig
• no_match – Kein passender Registereintrag
• ambiguous_participant – Mehrere passende Registereinträge
• not_current – Teilnahme derzeit nicht wirksam
• stale_data – Registerdaten veraltet
• lookup_error – Registerabfrage fehlgeschlagen

Verfügbar bei der IBAN-Validierung über REST sowie über validate_iban und validate_iban_batch per MCP. Bei der IBAN-Generierung werden die Felder mitgeliefert, wenn Bankdetails zurückgegeben werden. Die separaten BIC- und Bankleitzahl/Kontonummer-Prüfungen liefern diese Felder nicht.

Geprüft wird die Teilnahme der Bank. Das bestätigt weder die Existenz oder Zahlungsfähigkeit eines Kontos noch ein Mandat oder den Erfolg einer Zahlung. SCT Inst bestätigt die Teilnahme am Verfahren, keine Live-Erreichbarkeit über RT1/TIPS oder garantierte Echtzeitausführung für ein bestimmtes Konto.

Datenquelle: European Payments Council (EPC).