SEPA · Bankteilnahme · API-Antworten

Die SEPA-Teilnahme einer Bank mit der IBAN-Test-API prüfen

Prüfen Sie anhand einer IBAN-Validierungsantwort die Teilnahme einer Bank an SEPA-Basislastschrift, Firmenlastschrift, Überweisung und Echtzeitüberweisung. Betrachten Sie jedes Verfahren getrennt und unterscheiden Sie zwischen bestätigter und unbekannter Teilnahme.

Diese Anleitung erläutert die Antwortfelder und enthält ein Python-Beispiel zum Auswerten einer Live-Antwort oder gespeicherten JSON-Datei. Geprüft wird die Bankteilnahme, nicht die Fähigkeit eines bestimmten Kontos, eine Zahlung auszuführen.

Teststand des Beispiels: Die Auswertung hat sieben lokale Tests zu unabhängigen Verfahren, fehlenden Daten, ungültigen IBANs, technischen Fehlern und fehlerhaften Feldern bestanden. Auch der Offline-Befehl wurde ausgeführt. Die Testdaten stammen nicht aus einer echten Bankabfrage; eine authentifizierte Live-API-Prüfung wurde für dieses Beispiel nicht durchgeführt.

Was die vier Felder bedeuten

Die IBAN-Test-API gleicht die Teilnahme mit den Teilnehmerregistern des European Payments Council ab. Die Verfahren beschreiben unterschiedliche Zahlungsdienste; eine Bestätigung für eines belegt nicht die Teilnahme an den anderen. Die zugrunde liegenden Listen finden Sie in den EPC-Teilnehmerregistern.

1. Die IBAN prüfen

Verwenden Sie den normalen Endpunkt zur IBAN-Prüfung. Für diesen Ablauf ist kein zusätzlicher SEPA-Aufruf erforderlich:

POST https://www.iban-test.eu/api/v2/iban/validate
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{"iban":"DE89 3704 0044 0532 0130 00"}

Die obige IBAN ist ein Beispiel, keine Zahlungsanweisung. Prüfen Sie zuerst HTTP-Status und Validierungsergebnis. Eine verwertbare Antwort für eine gültige IBAN enthält code: 2100 und error: false. Die SEPA-Felder stehen anschließend unter details.sepa, sofern die API sie liefert. Die separaten Endpunkte zur BIC-Prüfung und deutschen Kontoprüfung liefern diese SEPA-Felder nicht.

2. „Bestätigt“ und „unbekannt“ unterscheiden

Jedes Verfahren enthält status und reason:

• confirmed: Die API hat einen eindeutigen aktuellen Registertreffer für dieses Verfahren gefunden.
• unknown: Die API konnte die Teilnahme nicht bestätigen. Das bedeutet nicht, dass die Bank das Verfahren nicht unterstützt.

Der folgende Ausschnitt dient ausdrücklich der Veranschaulichung. Er zeigt, warum vier getrennte Spalten hilfreicher sind als ein einzelnes Kennzeichen „SEPA unterstützt“:

{
  "sddCore": {"status": "confirmed", "reason": "matched"},
  "sddB2b":  {"status": "unknown",   "reason": "no_match"},
  "sct":     {"status": "confirmed", "reason": "matched"},
  "sctInst": {"status": "unknown",   "reason": "stale_data"}
}

In diesen Testdaten sind Core und SCT bestätigt. B2B bleibt unbestätigt, und das Ergebnis für Echtzeitüberweisungen beruht auf veralteten Daten. Keiner dieser unbekannten Werte ändert das ursprüngliche IBAN-Prüfergebnis.

3. Das Beispiel offline ausführen

Entpacken Sie den Download und führen Sie Folgendes aus:

python3 sepa_check.py --response example-response.json

Dabei wird keine Netzwerkanfrage gesendet und kein Token benötigt. Das Programm gibt eine JSON-Zusammenfassung mit iban_status, Bankinformationen und vier getrennten Verfahrensergebnissen aus. source: "offline_file" kennzeichnet die Eingabequelle. Die mitgelieferte Datei nennt eine fiktive Bank und darf nicht als Nachweis über ein echtes Institut verwendet werden.

Fehlen in einer gespeicherten Antwort die SEPA-Felder, gibt der Helfer unknown mit missing_response_data zurück. Dieser Grund ist eine lokale Markierung des Beispiels, kein Grundcode der IBAN-Test-API. Unerwartete Statuswerte oder fehlerhafte Verfahrensobjekte stoppen das Programm, statt stillschweigend akzeptiert zu werden.

4. Eine Live-Antwort prüfen

python3 sepa_check.py --iban "DE89 3704 0044 0532 0130 00"

Das Programm fragt Ihren Token ab, ohne ihn anzuzeigen. Alternativ stellen Sie IBAN_TEST_API_TOKEN über die Geheimniskonfiguration Ihrer Ausführungsumgebung bereit. Ein Live-Durchlauf führt eine IBAN-Prüfanfrage aus und belastet Ihr API-Kontingent. Der Helfer verwendet ein Timeout, prüft TLS, folgt keinen Weiterleitungen und wiederholt Anfragen nicht automatisch.

Verwenden Sie unter Windows gegebenenfalls py -3 statt python3. Der Befehl endet mit Code 0 bei gültiger IBAN, selbst wenn ein oder mehrere Verfahren unbekannt sind; mit 2 bei fachlich ungültiger IBAN und mit 1 bei einem Betriebs- oder Eingabefehler. Prüfen Sie die Verfahrensfelder separat, statt Exit-Code 0 als „alle Verfahren bestätigt“ zu interpretieren.

Ein unbekanntes Ergebnis verstehen

Speichern Sie Status und Grund gemeinsam. Zeigen Sie bei unbekannten Ergebnissen „Teilnahme konnte nicht bestätigt werden“ an und bearbeiten Sie diese Fälle gemäß dem Prüfprozess Ihrer Anwendung. Kennzeichnen Sie die IBAN nicht automatisch als ungültig und behaupten Sie nicht, die Bank könne diese Zahlungsart nicht ausführen.

API-Fehler von Teilnahmeergebnissen trennen

Ein HTTP-Authentifizierungsfehler, erschöpftes Kontingent oder Serverfehler ist kein Bankteilnahme-Ergebnis unknown. Das Beispiel stoppt vor der Verfahrensauswertung, wenn bereits die Anfrage fehlschlägt. Ebenso führt eine IBAN mit ungültiger Prüfsumme zu keiner Verfahrensentscheidung. So wird aus einem nicht verfügbaren Dienst keine irreführende Aussage über die Fähigkeiten einer Bank.

Führen Sie die enthaltenen Offline-Tests mit python3 -m unittest -v aus. Beginnen Sie bei größeren Eingabelisten mit der CSV-und-Python-Anleitung und behalten Sie beim Erweitern der Ausgabe für jedes Verfahren ein eigenes Status-Grund-Paar bei.

Technische Referenz: IBAN-Test-API-Dokumentation und SEPA-Grundcodes. Eine IBAN-Prüfung und bestätigte Bankteilnahme belegen weder Kontoinhaberschaft, Kontoexistenz, Mandat, verfügbare Mittel noch Zahlungserfolg.

API-Konto anlegen API-Kontingente vergleichen