Integration mit Payment Gateways: Flow, Retouren, Reconciliation

Vollständiger Artikel

💡 18+. Technisches Material für iGaming-Plattformen, Betreiber und Zahlungsanbieter. Kein Aufruf zum Spiel.

1) Die Rolle der Zahlungsorchestrierung in iGaming

Die Kasse ist die „Arterie“ der Plattform: Sie akzeptiert Einzahlungen, initiiert Cashouts, verarbeitet Retouren/Chargeback ™ und synchronisiert sich mit dem Wallet (Ledger). Aus einem Fehler oder einer Verzögerung wird hier schnell ein finanzielles und Compliance-Risiko. Die Aufgabe der Architektur ist ein schneller und nachweislich korrekter Cashflow bei eventuellen Störungen.

2) Basis-Flow mit PSP (State Map)

2. 1 Kaution (State Card)

1. create_intent (INITIATED) → die Schaffung einer Zahlungsabsicht auf der Plattformseite.

2. authorize (AUTHORIZED) → Hold in PSP (optional - capture).

3. 3-DS/AVS/KYC-Haken → zusätzliche Risiko-/Regulierungskontrollen.

4. capture (CAPTURED) → Abbuchung; Geldbörse Kredit.

5. failed/expired/canceled → Entschädigung und intent Schließung.

2. 2 Cashout (withdrawal)

request → die Validationen die RG/AML/Limits → payout_initiated → payout_settled/failed.

Vier-Augen-Bestätigungen für VIP/große Beträge, Velocity-Limits und Geo-Regeln.

2. 3 Void / Refund

void: Stornierung vor capture (entfernt hold).

refund: teilweise/vollständige Rückerstattung nach capture.

Bei Kartenschemata die einzelnen Zustände „submitted/processed“.

Invariant: Die Wahrheit über das Gleichgewicht des Spielers ist die Brieftasche. PSP-Designs verändern das Gleichgewicht nicht direkt; nur durch den Befehl 'wallet. credit/debit 'mit Idempotenz.

3) Idempotenz, Schlüssel und Retrays

Jede Schreiboperation trägt einen 'X-Idempotency-Key' und eine' X-Trace-Id'.

Die Schlüsselzusammensetzung ist an Geschäftsparameter gebunden (z.B. 'intent _ id + amount + currency').

Wiederholung mit dem gleichen Schlüssel → das gleiche Ergebnis (200 mit dem alten Körper).

Retrays mit exponentiellem Backoff + Jitter, harte' Timeout/Deadline'.

4) 3-DS, AVS, velocity, Betrugsbekämpfung

3-DS 2. x: vorzugsweise Challenge-Flow mit Device-Fingerprinting; ECI/CAVV/DSTransID im Protokoll speichern.

AVS/CVV: Integrieren Sie Verifizierungscodes in Telemetrie- und Routing-Regeln.

Velocity: Limits für Betrag/Anzahl/Karten/ASN/Geräte (1h/24h/7d).

Verhaltenssignale: Geo/Zeitzonendiskrepanz, viele Karten/wenige Einzahlungen, schnelle Cachouts.

5) Routing und PSP-Kaskaden

Regeln: Geo, BIN-Bereiche, Kartentyp, Kosten, Conversion, Risiko-Score.

Kaskade: PSP1 → PSP2 bei Ausfall, ohne den Korb zu verlieren (idempotent token).

A/B/Multi-Armed Bandit: Optimierung von Conversion und Kosten.

Fail-open/closed: Für fragwürdige Fehler safe-default anwenden (z.B. Wiederholung durch ein anderes Merchant), aber nicht für dubiose Aufnahme.

6) API-Verträge (Referenzfragmente)

6. 1 Schaffung eines Intents auf der Einzahlung


POST /v1/cashier/intents
Headers: X-Idempotency-Key, X-Trace-Id
{
"player_id":"p_123",  "amount":{"amount":50. 00,"currency":"EUR"},  "method":"card",  "metadata":{"brand_id":"A","region":"EU"}
}
→ 201 { "intent_id":"pi_001","status":"INITIATED" }

6. 2 Autorisierung/Erfassung


POST /v1/cashier/intents/pi_001/authorize
→ 200 { "status":"AUTHORIZED","psp_ref":"psp_aa1","eci":"05","cavv":"…" }

POST /v1/cashier/intents/pi_001/capture
→ 200 { "status":"CAPTURED","capture_id":"cap_001" }

6. 3 Void / Refund


POST /v1/cashier/captures/cap_001/refunds
{ "refund_id":"rf_001", "amount":{"amount":10. 00,"currency":"EUR"} }
→ 202 { "status":"REFUND_SUBMITTED" }

6. 4 PSP Webhooks → Plattform (HMAC/EdDSA signiert)


POST /webhooks/psp
X-Signature: sha256=…
{
"event":"payment. captured",  "psp_ref":"psp_aa1",  "intent_id":"pi_001",  "amount":{"minor_units":5000,"currency":"EUR"},  "occurred_at":"2025-10-23T12:05:01Z",  "idempotency_key":"cap_001"
}

Der Empfänger ist verpflichtet: Signatur/Timestamp/Nonce zu überprüfen, 'event _ id' zu deduplizieren, mit 'intent _ id' zu korrelieren.

7) Synchronisation mit Wallet (Ledger)

Nach der Aufnahme: der Befehl 'wallet. credit'(idempotent) → das Gleichgewicht des Spielers.

Refund: `wallet. debit'(oder 'wallet. hold_release' für void).

Cashout: 'wallet. debit` → `payout` в PSP; nach dem Webhook 'payout _ settled' - schließt die Saga.

Die Saga "deposit':" authorize → capture → credit "mit Entschädigungen für Ausfälle.

Die Saga „refund/payout“: „request → submitted → settled/failed“ mit Wiederholung und Deduplizierung.

8) Reconciliation (Abstimmung) - das Herz der Geldkontrolle

8. 1 Täglicher Abgleich

Holen Sie sich den PSP-Settlement-Bericht (nach Merchant/Datum/Währung).

Vergleichen Sie mit der Registrierung der Plattform: „intents/captures/refunds/payouts“ ↔ „wallet entries“.

Kategorisieren:

Match: Alles ist ok, Timing: Verzögerung der Anzahl der Berichte, missing_psp: in der Plattform gibt es, in der PSP gibt es keine, missing_platform: in der PSP gibt es, in der Plattform gibt es keine, amount_mismatch: Diskrepanz zwischen Betrag/Währung/Gebühr.
Auto-Regeln für Timing, Tickets/Eskalationen für Mismatch.

8. 2 Technischer Prozess

Berichte werden von SFTP/API nach Zeitplan gezogen (Retrays + Integritätskontrolle).

Parsing → Normalisierung → deterministisches Mupping ('psp _ ref', 'intent _ id', 'capture _ id').

Der Abgleich erfolgt in OLAP (ClickHouse/BigQuery) nach Invarianten.

BI-Schaufenster: Umbauten, Ausfallursachen, Kanalkosten, Schließzeiten.

8. 3 Alerts

`% mismatch` > X p. p., Anstieg 'missing _ platform', Wachstum 'amount _ mismatch', Abweichung 'deposit _ success' über Kanal/geo, Aging von nicht gekoppelten Transaktionen> N Tage.

9) Chargeback / Dispute

Lebenszyklus: notification → evidence → representment → arbitration.

Speichern Sie evidence-Pakete (KYC, IP/ASN, Gerät, 3-DS Ergebnisse, Usage-Logs).

Enge Verbindung zu Risiko/Anti-Fraud: Karten-/Geräte-/ASN-Verbote auf Routing-Ebene.

KPI: win-rate, cost-to-serve, time-to-close.

10) Telemetrie und SLO

p95 Autorisierung: ≤ 3 s, p99: ≤ 6-8 s (abhängig von 3-DS/Banken).

Deposit Success Rate nach Geo/PSP: Ziel ≥ 85% (realistische Benchmark).

Reconciliation lag: Bericht geschlossen ≤ T + 1 Tag; aging unsauber

Refund turnaround: ≤ T + 1 für den Versand ≤ T + 5 für die Einschreibung (nach dem Schema).

Metriken: Fehlerrate durch Codes, Fehler durch 3-DS/AVS, Decline-Matrix (Bank/Code), Kosten pro Erfolg, Webhook-Lag, Retry-Storms.

11) Sicherheit und Compliance

mTLS zu PSP + OAuth2/Anforderungssignaturen; Schlüssel/Zertifikate pro Marke/Region.

PCI DSS: PAN-Tokenisierung, niemals CVV speichern, Zonensegmentierung.

WORM-Audit: Kreta-Operationen (manueller Refund/void, Merchantwechsel).

RG/AML: Füße vor der Aufnahme/Auszahlung; Sanklisten/RER; SAR/STR Berichterstattung.

PII Wohnsitz: Protokolle/Berichte in der Region; RLS/Masking in BI.

12) Beobachtbarkeit und Protokollierung

Strukturierte Protokolle (JSON) mit 'trace _ id', 'psp _ ref', 'intent _ id/capture _ id/refund _ id', Codes und Zeitdauern.

OpenTelemetry auf HTTP/gRPC/DB/Warteschlangen; 100% Sampling für Fehler/monetäre Anomalien.

NOC Dashboards: Conversions nach Kanal, p95, Opt-out nach Code, Webhook-lag, DLQ.

13) Chaos-und DR-Praktiken

PSP Fall: Autokaskade/„ Pause neue Captures “.

Verzögerung von Webhooks: Dedup + Neuabgleich über Pull-API.

Out-of-Order: Idempotenz und Statusmaschine auf der Plattform.

Regionale Outage: Asset-Liability/Asset-Asset, RPO ≤ 5 min, RTO ≤ 30 min.

14) Checklisten

Plattform/Betreiber

Alle Schreibpfade mit 'X-Idempotency-Key', 'X-Trace-Id'.
Routing/PSP Kaskaden mit Telemetrie und Limits.
3-DS/AVS/velocity enthalten; Risikoregeln und Verbote.
Webhooks sind signiert; dedup durch 'event _ id'; DLQ.
Sagi deposit/refund/payout; Kompensation ohne „manuelle Korrekturen“.
Täglicher Abgleich T + 1, Schaufenster mismatch, Alerts.
PCI-Zone, PAN-Tokenisierung; WORM-Audit von Kreta-Operationen.
RG/AML-Fuß vor der Erfassung/Auszahlung.

PSP-Integration/Kassenrückseite

Die Fehlerverträge sind normalisiert; Mapping von Decline-Codes.
Wiederholungen sind sicher; Idempotenzschlüssel sind dokumentiert.
Timeouts/Retrays/Jitter, Circuit Breaker, Rate Limits.
Berichte sind über API/SFTP verfügbar, Integrität ist garantiert.

15) Anti-Muster (rote Fahnen)

Der Saldo ändert sich durch das PSP-Webhook ohne einen expliziten Befehl in der Brieftasche.

Keine Idempotenz → doppelte Abschreibungen/Kredite.

Integrierte Kasse im iFrame des Spieleanbieters (Kontrollverlust RG/AML/Telemetrie).

Gemeinsame Merchant-Schlüssel für mehrere Marken/Regionen.

Kein T + 1-Abgleich, manuelle Excel-Mappings.

BI/regulatorische Berichte direkt von der OLTP-Kasse.

Fehler werden 3-DS/AVS nicht protokolliert/analysiert.

Webhooks ohne Signatur/Fenstervalidierung → Replika.

Manuelle Änderungen von Zahlungsstatus/Salden in der DB.

16) Das Ergebnis

Eine zuverlässige Integration mit Zahlungsgateways ist eine Orchestrierung, kein „API-Durchlauf“. Der Erfolg wird sichergestellt durch:

1. Idempotente Geldkommandos und Sagas (authorize/capture/refund/payout).

2. Routing und PSP-Kaskaden mit 3-DS/AVS/velocity und echter Telemetrie.

3. Täglicher Abgleich (Reconciliation) und strikte Berücksichtigung von Diskrepanzen.

4. Sicherheit und Compliance (mTLS, Signaturen, PCI, RG/AML, WORM).

Durch den Aufbau dieser Grundlagen erhöht die Plattform die Umwandlung von Einlagen, reduziert das Risiko von Takes und Chargebacks und wird sicher auditiert - auch in der Spitze des Datenverkehrs und bei Ausfällen externer Anbieter.