Abrechnungs- und Zahlungs-APIs sauber anbinden

Idempotenz bedeutet, dass eine Anfrage mit demselben Idempotenz-Schlüssel beliebig oft wiederholt werden kann, ohne dass sie mehrfach wirkt. Bei einer Zahlung verhindert das doppelte Abbuchungen, wenn eine Antwort verloren geht oder ein automatischer Retry ausgelöst wird.

In der Praxis erzeugt die Anwendung pro Geschäftsvorgang einen eindeutigen Schlüssel, meist eine UUID, und sendet ihn bei jedem Versuch mit. Der Zahlungsanbieter erkennt die wiederholte Anfrage am Schlüssel und liefert das ursprüngliche Ergebnis zurück, statt die Aktion erneut auszuführen.

Ohne diesen Mechanismus wird aus jedem automatischen Retry ein Risiko für eine zweite Buchung. Idempotenz ist deshalb die Grundvoraussetzung, bevor überhaupt über Wiederholungen nachgedacht wird.

Timeouts und Backoff gehören zusammen, weil eine Anfrage ohne klares Zeitlimit die Anwendung blockiert und ein sofortiger erneuter Versuch die Gegenseite zusätzlich belastet. Jede Anfrage an eine externe API braucht ein explizites Timeout, das kürzer ist als das Zeitlimit des aufrufenden Kontexts.

Nach einem Fehler oder Timeout sollte nicht sofort erneut gesendet werden. Ein exponentielles Backoff mit zufälligem Zuschlag verteilt mehrere gleichzeitige Fehler über die Zeit und vermeidet synchronisierte Lastspitzen beim Anbieter.

Typische Wartezeiten zwischen den Versuchen:

1. Eine Sekunde nach dem ersten Fehlschlag.
2. Zwei Sekunden nach dem zweiten Fehlschlag.
3. Vier bis acht Sekunden nach dem dritten Fehlschlag, danach Abbruch und manuelle Prüfung.

Ein Webhook muss anhand seiner Signatur geprüft werden, bevor die Anwendung ihm vertraut. Die meisten Anbieter signieren den übertragenen Inhalt mit einem gemeinsamen Geheimnis; die Anwendung berechnet die Signatur selbst und vergleicht sie zeitkonstant mit der übermittelten.

Dazu gehört eine Prüfung auf Wiederholung: Jeder Webhook sollte eine eindeutige Event-ID tragen, die protokolliert wird, damit dieselbe Nachricht nicht zweimal verarbeitet wird. Ohne Verifizierung kann jeder, der die URL kennt, gefälschte Zahlungsereignisse einspielen.

Die Antwort auf den Webhook sollte innerhalb weniger Sekunden erfolgen. Die eigentliche Verarbeitung passiert danach, getrennt von der Zustellung.

Weil ein Webhook-Endpunkt innerhalb weniger Sekunden antworten muss, sonst wertet der Anbieter die Zustellung als fehlgeschlagen und wiederholt sie. Die eigentliche Verarbeitung, etwa Datenbank aktualisieren, Benachrichtigungen versenden oder Folgeaktionen auslösen, gehört in einen Queue-Job.

Der Webhook-Handler validiert die Signatur, speichert das Event und reiht den Job in die Queue ein; die Antwort geht sofort zurück. Schlägt die Verarbeitung fehl, übernimmt die Queue mit eigenen Wiederholungs- und Backoff-Mechanismen, ohne den Anbieter erneut zu belasten.

Jede Anfrage an eine Abrechnungs-API und jede eingehende Antwort oder jeder Webhook sollten protokolliert werden, inklusive Idempotenz-Schlüssel, Statuscode und der relevanten Nutzlast ohne sensible Felder wie vollständige Kartennummern. Nur so lässt sich im Streitfall rekonstruieren, was wann passiert ist.

Für Support und Buchhaltung ist entscheidend, eine interne Transaktion mit der ID des Zahlungsanbieters zu verknüpfen. Ohne diese Zuordnung dauert die Klärung eines einzelnen strittigen Falls häufig länger als die gesamte technische Integration.

Über die Sandbox- oder Testumgebung des jeweiligen Anbieters, die reale Endpunkte simuliert, ohne echtes Geld zu bewegen. Dort lassen sich typische Fehlerfälle gezielt auslösen: abgelehnte Zahlung, abgelaufene Karte, Timeout oder doppelte Anfrage.

Automatisierte Tests sollten diese Fehlerfälle ebenso abdecken wie den Erfolgsfall. Ein Mock der eigenen Abstraktionsschicht erleichtert das, weil er ohne Netzwerkzugriff läuft; vor dem Wechsel in den Live-Betrieb lohnt sich zusätzlich ein Testlauf mit einem echten, minimalen Betrag, sofern der Anbieter das vorsieht.

Fehlerfälle gehören in einen klaren, eindeutigen Zustand: offen, fehlgeschlagen, erfolgreich oder zurückerstattet, nie unbekannt. Ein regelmäßiger Abgleich zwischen den eigenen Datensätzen und den Berichten des Zahlungsanbieters deckt Abweichungen auf, etwa Zahlungen, die beim Anbieter erfolgreich waren, in der eigenen Datenbank aber fehlen.

Monitoring sollte Fehlerquote, Latenz und die Länge der Warteschlange der Queue-Jobs im Blick behalten und bei Auffälligkeiten aktiv benachrichtigen. Niemand sollte zufällig im Log darüber stolpern müssen. Ein Alarm, wenn die Fehlerquote eines Zahlungsanbieters plötzlich steigt, ist wichtiger als ein Dashboard, das niemand ansieht.

Weil der eigene Code dann gegen eine selbst definierte Schnittstelle programmiert, etwa ein PHP-Interface mit Methoden wie charge, refund und getStatus. Das SDK eines Anbieters ruft er nicht direkt auf. Der konkrete Anbieter steckt danach in einer austauschbaren Implementierung dahinter.

Bei einer Reise-Buchungsplattform, die ich über mehrere Jahre mitbetreut habe, gehörte die Anbindung neuer Abrechnungs-APIs zu meinen Aufgaben. Das passierte im laufenden Betrieb, in kleinen, einzeln testbaren Schritten und mit der Möglichkeit, bei Problemen zurückzurollen.

Diese Kapselung schützt zudem vor einer zu engen Bindung an einen Anbieter. Ändern sich Preisstruktur oder Konditionen, lässt sich eine zweite Implementierung ergänzen, ohne den Rest der Anwendung zu berühren.