PHP-Integrationsanleitung

Eine IBAN in einem PHP-Formular prüfen

Erstellen Sie ein kleines serverseitiges Formular, das eine IBAN mit IBAN-Test prüft, Ihren API-Token vom Browser fernhält und Kunden verständlich informiert, wenn eine Prüfung nicht abgeschlossen werden kann.

Teststand des Beispiels: Die enthaltenen Tests prüfen mit einer simulierten Übertragung und Testzugangsdaten gültige, ungültige und nicht verfügbare Ergebnisse, CSRF-Abweisung, HTML-Maskierung und Wartezeiten. Sie simulieren eine fehlgeschlagene Übertragung, um die Timeout-Behandlung ohne Netzwerkwartezeit zu prüfen. Dies ist kein authentifizierter Live-API-Test. Nutzen Sie die Tests beim Anpassen des Beispiels und prüfen Sie anschließend Ihre eigene Testumgebung, bevor Sie echte Kundeneingaben freigeben.

1. Den Anfrageablauf verstehen

Der Browser zeigt ein gewöhnliches HTML-Formular. Beim Absenden werden die IBAN und ein CSRF-Token aus der Sitzung an Ihre PHP-Anwendung übertragen. PHP prüft den Formular-Token, begrenzt die Eingabe und entfernt normale Leerzeichen, bevor es die API anfragt. Der Browser verbindet sich niemals direkt mit IBAN-Test und erhält den Bearer-Token nicht.

Das Backend sendet JSON an POST https://www.iban-test.eu/api/v2/iban/validate. Es liest den HTTP-Status und die JSON-Felder, ordnet das Ergebnis einer festgelegten Benutzermeldung zu und gibt eine weitere HTML-Seite zurück. Die Schnittstelle ist in der IBAN-Test-API-Dokumentation beschrieben.

Browser form → your PHP backend → IBAN-Test API
Browser result ← controlled message ← HTTP status and JSON

Behalten Sie diese Aufteilung auch bei einer AJAX-Anpassung bei: JavaScript darf Ihre eigene Anwendung aufrufen, die Authentifizierung gegenüber IBAN-Test bleibt jedoch auf dem Server. Ein Token in einer JavaScript-Datei oder einem minimierten Bundle ist nicht geheim.

2. Das Beispiel lokal starten

Entpacken Sie die ZIP-Datei und wechseln Sie in das Verzeichnis demo. Prüfen Sie mit php -v und php -m die PHP-Version und die cURL-Erweiterung. Sessions und JSON müssen ebenfalls verfügbar sein. Composer ist nicht erforderlich. Führen Sie zunächst die enthaltenen Offline-Prüfungen aus:

php tests/run.php

Für eine tatsächliche API-Prüfung benötigen Sie einen Token aus Ihrem IBAN-Test-Konto. Verwenden Sie in Bash eine verdeckte Eingabe, damit der Wert nicht als Klartextbefehl in der Shell-Historie landet:

read -r -s -p 'IBAN-Test API token: ' IBAN_TEST_API_TOKEN
printf '\n'
export IBAN_TEST_API_TOKEN
php -d display_errors=0 -d post_max_size=4K -S 127.0.0.1:8080 -t public

Öffnen Sie http://127.0.0.1:8080. Der Server lauscht nur auf Ihrem Rechner. Stoppen Sie ihn mit Strg+C und führen Sie anschließend unset IBAN_TEST_API_TOKEN aus. Der PHP-Entwicklungsserver dient dieser lokalen Übung. Lassen Sie public als Dokumentenstamm eingestellt, damit Client, Tests und README außerhalb des ausgelieferten Verzeichnisses bleiben.

Ohne die Umgebungsvariable lädt das Formular trotzdem. Bei plausibler Eingabe zeigt es dann eine Nichtverfügbarkeitsmeldung, ohne die API anzufragen. Echte API-Anfragen erfordern ein aktives Konto und verbrauchen Kontingent.

3. Eingaben vorprüfen und das Formular schützen

Das Beispiel akzeptiert eine einzelne Zeichenkette mit höchstens 80 Bytes, normalisiert normale Leerzeichen und Groß-/Kleinschreibung und prüft ein einfaches Zeichenmuster. So werden offensichtlich ungeeignete Eingaben mit geringem Aufwand abgewiesen. Diese Prüfungen berechnen keine Prüfsumme und bestätigen keine gültige IBAN; dafür benötigt das Backend weiterhin das API-Ergebnis.

Ein zufälliger, in der Sitzung gespeicherter Token wird als verborgenes Feld mitgesendet und beim Absenden verglichen. Ein abweichender Token wird vor dem API-Aufruf abgewiesen. Außerdem gilt pro Sitzung eine Wartezeit von drei Sekunden zwischen Eingaben. Das hilft gegen wiederholtes Klicken, ist aber keine produktive Ratenbegrenzung, da Benutzer neue Sitzungen anlegen können.

Alle in HTML eingefügten Werte werden mit htmlspecialchars maskiert, auch die nach einem Fehler erneut angezeigte Eingabe. Die Implementierung maskiert Anführungszeichen explizit und ersetzt ungültige UTF-8-Sequenzen gemäß der PHP-Referenz zur Maskierung. Browserantworten verwenden Cache-Control: no-store. Session-Cookies verwenden HttpOnly und SameSite; die Optionen erläutert die PHP-Session-Dokumentation.

4. Eine begrenzte API-Anfrage senden

Der Client liest IBAN_TEST_API_TOKEN auf dem Server und sendet einen Authorization: Bearer-Header. Der Anfrageinhalt enthält nur die normalisierte IBAN:

{"iban":"DE89370400440532013000"}

Das Ziel ist im Code festgelegt. Formulareingaben können keinen Host auswählen. TLS-Zertifikat und Hostname werden weiterhin geprüft; Weiterleitungen sind deaktiviert. Der Verbindungsaufbau ist auf drei Sekunden, die gesamte Übertragung auf acht Sekunden begrenzt. Eine Antwort über 64 KiB bricht die Übertragung ab. Die Optionen beschreibt die PHP-cURL-Referenz.

Es gibt keine automatische Wiederholung. Nach einem Timeout kann unklar sein, ob der Anbieter die Anfrage verarbeitet hat; Wiederholungen können zusätzliches Kontingent verbrauchen. Deshalb zeigt die Seite einen vorübergehenden Fehler. Falls Ihre Anwendung später Wiederholungen ergänzt, definieren Sie eine begrenzte Strategie, die sowohl Wartezeit als auch Kontingent berücksichtigt.

5. Das richtige Ergebnis anzeigen

Prüfen Sie sowohl die erfolgreiche Übertragung als auch die Antwortfelder. Für diesen Endpunkt behandelt das Beispiel gemäß den dokumentierten Ergebniscodes drei Fälle:

• Gültig: HTTP 200, der ganzzahlige Wert code: 2100 und der boolesche Wert error: false müssen gemeinsam vorliegen.
• Ungültige Bankdaten: Eine korrekt aufgebaute HTTP-200-Antwort mit Code 3100, 3101 oder 3102 und dem booleschen Wert error: true fordert zur Korrektur auf. Widersprüchliche Antworten mit error: false gelten als nicht verfügbar.
• Nicht verfügbar: Authentifizierungs- oder Kontingentprobleme, andere HTTP-Statuswerte, Timeouts, unbekannte Codes und fehlerhaftes JSON erzeugen eine technische Fehlermeldung.

Eine nicht verfügbare Prüfung darf Kunden nicht mitteilen, ihre IBAN sei ungültig. Das Beispiel verwendet eigene Meldungen statt ungefilterter Anbietertexte. Ein gültiges Ergebnis bestätigt die formale Prüfung; es belegt weder Kontoinhaberschaft noch Kontoexistenz oder Zahlungserfolg.

6. Die Anwendung für den Betrieb vorbereiten

Verlangen Sie vor einer öffentlichen Freigabe eine Berechtigung innerhalb Ihrer Anwendung und begrenzen Sie den Kontingentverbrauch gemeinsam über Benutzer, Sitzungen und Anwendungsinstanzen hinweg. Binden Sie den Zugang bei Gastbestellungen an eine serverseitig autorisierte Bestellsitzung und ergänzen Sie Missbrauchsschutz. Die Sitzungswartezeit und CSRF-Prüfung allein schützen Ihr kostenpflichtiges Kontingent nicht.

Verwenden Sie HTTPS, sichere Cookies, einen produktionsgeeigneten PHP-Server und serverseitige Größenlimits für Anfrageinhalte. Konfigurieren Sie vertrauenswürdige Proxys ausdrücklich, wenn TLS vorgelagert endet. Stellen Sie Geheimnisse über Ihre Hosting-Umgebung bereit; PHP-FPM kann eine explizite Umgebungskonfiguration benötigen. Schließen Sie Tokens, IBAN-Anfrageinhalte und sensible Fehlerdetails aus Protokollen und Monitoring aus. Veröffentlichen Sie niemals eine Diagnoseseite, die die Umgebungsvariablen ausgibt.