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.
- Produktstand abgeglichen
- 16. September 2026
- Verantwortlich
- FoxPay Produktdokumentation
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
Zahlungsreferenz, Ereignistyp und Statusübergang atomar absichern. Eine pro Zustellversuch neue Delivery-ID allein verhindert keine doppelte Geschäftsaktion.
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
Fachlichen Ereignisschlüssel und angewandten Übergang atomar speichern.
- 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.
Kann ich den Zahlungsstatus per Merchant-API abfragen?
Der zusätzliche Merchant-Polling-Zugang ist derzeit nicht allgemein aktiviert. Nutzen Sie signierte Webhooks; eine gesonderte Freigabe und die aktuellen Schnittstellenregeln finden Sie in der API-Dokumentation.
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.