TECHNISCHER LEITFADEN / A2A
A2A-Payment-Status, Webhooks und Reconciliation
Ein belastbares Betriebsmodell für bankdirekte Zahlungen: Zustandsmaschine, idempotente Webhooks, Retry-Queue, Referenzen, Refunds und täglicher Abgleich.
- Zuletzt fachlich geprüft
- 30. Juli 2026
- Verantwortlich
- FoxPay Product & Compliance
01Statusmodell
Zustände explizit statt implizit modellieren
Created
Zahlung existiert, aber eine Bankautorisierung ist noch nicht bestätigt.
Pending
Ein Ergebnis ist offen; Fulfilment bleibt blockiert oder bewusst kontrolliert.
Paid
Serverseitig bestätigter Terminalzustand für die Bestellfreigabe.
Failed/Expired
Terminale Nichtzahlung; erneuter Versuch erhält eine neue Referenz.
02Webhooks
Jedes Ereignis sicher und genau einmal wirksam machen
Signaturprüfung
Raw Body, Timestamp und Signatur nach dokumentiertem Verfahren validieren.
Idempotency Key
Event-ID persistent speichern und doppelte Zustellung folgenlos quittieren.
Ack zuerst
Nach sicherer Persistenz schnell antworten und schwere Arbeit asynchron ausführen.
Out-of-order
Zustandsübergänge validieren, weil Ereignisse verspätet eintreffen können.
03Reconciliation
Täglicher Abgleich als kontrollierter Prozess
Drei Referenzen
Merchant Order, FoxPay Payment und Payout/Settlement getrennt speichern.
Differenzen
Fehlende, doppelte, abweichende oder lange offene Zahlungen klassifizieren.
Ownership
Technische und finanzielle Abweichungen haben benannte Verantwortliche.
Audit Trail
Statuswechsel, Event, Entscheidung und Korrektur nachvollziehbar protokollieren.
04Ablauf
Webhook-Verarbeitung
Ein robuster Handler trennt Annahme, Persistenz und fachliche Verarbeitung.
- 01
Empfangen
Raw Request und Metadaten begrenzt erfassen.
- 02
Verifizieren
Signatur, Alter und erlaubten Eventtyp prüfen.
- 03
Deduplizieren
Event-ID atomar persistieren.
- 04
Verarbeiten
Zustandsübergang idempotent anwenden.
- 05
Abgleichen
Abweichungen in Monitoring und Daily Reconciliation führen.
05Evidenz
Fehler- und Retry-Matrix
Nicht jeder Fehler darf gleich behandelt werden.
| Fehler | Reaktion | Ziel |
|---|---|---|
| Timeout | Mit Backoff erneut | Zustellung |
| Doppelt | Erfolg ohne Nebenwirkung | Idempotenz |
| Ungültige Signatur | Ablehnen + alarmieren | Sicherheit |
| Fachlich ungültig | Dead Letter + Review | Korrektur |
Logs dürfen keine Secrets oder unnötigen personenbezogenen Zahlungsdaten enthalten.
06FAQ
Häufige Fragen
Antworten zum aktuellen, fachlich geprüften Scope.
Warum werden Webhooks mehrfach zugestellt?
At-least-once-Zustellung schützt vor verlorenen Ereignissen. Der Empfänger muss deshalb idempotent arbeiten.
Darf der Browser die Bestellung freigeben?
Nein. Der Browser kann nur einen vorläufigen Zustand zeigen; die serverseitig bestätigte Zahlung steuert Fulfilment.
Wie oft sollte reconciled werden?
Die Frequenz hängt von Volumen und Betriebsrisiko ab. Ein täglicher automatisierter Abgleich plus zeitnahe Ausnahmebehandlung ist eine belastbare Basis.