Payment API integrieren: Ablauf und Fehlerfälle planen

Bestellung und Zahlungsversuch getrennt modellieren

Eine Bestellung ist die geschäftliche Grundlage; ein Zahlungsversuch ist ein technischer Vorgang mit eigenem Verlauf. Verwenden Sie stabile Referenzen für beide und speichern Sie ihre Beziehung. Eine Bestellung kann eine Klärung benötigen, ohne dass deshalb automatisch ein weiterer Zahlungsversuch zulässig ist. Legen Sie außerdem fest, welcher Händlerkontext und welche Umgebung verwendet werden. Bei mehreren Shops muss die Anwendung zuverlässig die richtige Verbindung auswählen. Diese Angaben sollten aus vertrauenswürdigen serverseitigen Daten stammen und nicht allein aus veränderbaren Eingaben im Browser übernommen werden.

Integration und API

Betrag und Währung eindeutig übergeben

Jede API legt fest, wie Beträge dargestellt werden. Übernehmen Sie diese Darstellung genau, statt Gewohnheiten aus einem anderen System weiterzuverwenden. OrsunPay dokumentiert Dezimalzeichenfolgen für Beträge. Prüfen Sie zusammen mit der Währung, ob der Wert zur endgültigen Bestellung gehört. Ein Rabatt oder eine Änderung der Stückzahl muss vor der Erstellung berücksichtigt werden. Verfolgen Sie einen konkreten Beispielbetrag durch Auftrag, Anfrage und Ergebnis. Eine richtig aussehende Checkout-Seite schützt nicht davor, dass im Hintergrund unterschiedliche Systeme mit verschiedenen Zahlenformaten arbeiten.

Gehostete Zahlungsseite

Die verlorene Antwort als normalen Fehlerfall behandeln

Eine Anfrage kann den Server erreichen, obwohl ihre Antwort beim Aufrufer nicht ankommt. Dann ist zunächst unbekannt, ob die Zahlung erstellt wurde. Eine blinde Wiederholung kann einen zweiten Vorgang erzeugen. Nutzen Sie deshalb die dokumentierte Idempotenz und halten Sie fest, welche fachliche Anfrage zu welchem Schlüssel gehört. Unterscheiden Sie eine Wiederholung derselben Anfrage von einem bewusst neu angelegten Zahlungsversuch. Die Regeln sollten im Integrationskonzept stehen, damit nicht jeder Aufrufer bei einem Zeitlimit eine eigene, möglicherweise widersprüchliche Strategie verwendet.

Webhooks vor der Verarbeitung authentifizieren

Ein öffentlicher Benachrichtigungsendpunkt darf eine Bestellung nicht allein aufgrund eines eingehenden JSON-Dokuments verändern. Verifizieren Sie den vorgesehenen Nachweis und halten Sie die geheimen Schlüssel aus dem Browser fern. OrsunPay beschreibt HMAC-SHA256 über die unveränderten Rohbytes des Nachrichtenkörpers. Eine vorherige Umformatierung kann die Prüfung beeinträchtigen. Die offiziellen Leitfäden von Stripe und Mollie erläutern ebenfalls den Stellenwert serverseitiger Ereignisse. Protokollieren Sie genug für eine spätere Untersuchung, aber vermeiden Sie unnötige vertrauliche Inhalte in frei zugänglichen Logs.

Eine fachliche Aktion nur einmal ausführen

Nach der technischen Prüfung muss Ihre Anwendung entscheiden, welche Zustandsänderung erlaubt ist. Derselbe Zahlungserfolg darf nicht zweimal eine Lieferung oder Freischaltung auslösen. Speichern Sie die Verarbeitung so, dass wiederholte Ereignisse nachvollziehbar bleiben, ohne die Aktion erneut auszuführen. Berücksichtigen Sie außerdem Benachrichtigungen, die verspätet eintreffen. Die Rückkehrseite kann dem Kunden den bekannten Stand erklären, sie ist aber nicht selbst der Zahlungsnachweis. Die Entscheidung über die Auftragserfüllung sollte aus einem verifizierten serverseitigen Ergebnis und Ihren Bestellregeln entstehen.

Betrieb und Übergabe mitentwickeln

Der Support benötigt eine Referenzsuche und eine klare Erklärung für offene Vorgänge. Definieren Sie, wann ein interner Verarbeitungsschritt wiederholt werden darf und wann der zuständige PSP einbezogen wird. OrsunPay vereinheitlicht Verbindungen zu Ihren eigenen Konten; es ersetzt nicht deren Verträge oder Zulassungsentscheidungen. Bestätigen Sie außerdem die tatsächliche Veröffentlichung benötigter SDKs oder Pakete. Vorhandener Repository-Code ist noch kein öffentlich verfügbares Paket. Eine Übergabe ist erst brauchbar, wenn eine andere Person einen ungeklärten Beispielauftrag mit den vorgesehenen Informationen bearbeiten kann.

• Eine verlorene Antwort nach der Erstellung simulieren.
• Ungültige Signaturen und doppelte Ereignisse prüfen.
• Betrag, Währung und Händlerkontext nachvollziehen.
• Die Entscheidung bei unbekanntem Ergebnis dokumentieren.
• Support und Entwicklung an derselben Referenz arbeiten lassen.

Quellen

• Stripe-Dokumentation zu Webhooks
• Mollie-Dokumentation zu Zahlungen