Integrazione con i gateway di pagamento: flow, rimborsi, richiami

Testo completo dell'articolo

💡 18+. Materiale tecnico per piattaforme iGaming, operatori e provider di pagamenti. Non una chiamata al gioco.

1) Ruolo dell'orchestra di pagamento nel iGaming

Cassa - «arteria» della piattaforma: accetta i depositi, avvia le cashout, elabora i rimborsi e la sincronizzazione con il portafoglio (Ledger). Un errore o un ritardo qui diventa rapidamente un rischio finanziario e di compliance. Attività di architettura: flusso di cassa rapido e dimostrabile in caso di guasti.

2) Flow di base con PSP (mappa degli stati)

2. 1 Deposito (carta di stato)

1. create _ intent (INIZIATED) crea un'intenzione di pagamento sul lato della piattaforma.

2. AUTHORIZED (AUTHORIZED) Collide in PSP (opzionale - capture immediata).

3. 3-DS/AVS/KYC hooks →.

4. CAPTED (CAPTURE): prelievi portafoglio credit.

5. failed/expired/canceled compensazione e chiusura dell'intent.

2. 2 Cache (withdrawal)

richiest di convalida RG/AML/limiti di payout _ iniziated payout _ settled/failed.

Conferma dei quattro occhi per le somme VIP/ingenti, limiti velocity e geo-regole.

2. 3 Void / Refund

void - Annulla a capture (rimuove hold).

refund: restituzione parziale/totale dopo capture.

Per i diagrammi di carte, i singoli stati'sottomitted/processed '.

La verità sul bilanciamento del giocatore è il portafoglio. I modelli PSP non cambiano direttamente l'equilibrio; solo attraverso il comando wallet. credit/debit'con idipotenza.

3) Idempotenza, chiavi e retrai

Ogni operazione write porta X-Idempotency-Key e X-Trace-ID.

La composizione della chiave è associata a parametri aziendali (ad esempio, 'intent _ id + amount + currency').

Una ripetizione con la stessa chiave ha lo stesso risultato (200 con il vecchio body).

Retrai con backoff esponenziale + jitter, rigide'timeout/deadline '.

4) 3-DS, AVS, velocity, antifrode

3-DS 2. x - Preferibilmente challenge-flow con device-fingerprinting Tieni il ECI/CAVV/DSTransID nel registro.

AVS/CVV: includere i codici di verifica nella telemetria e nelle regole di routing.

Velocity: limiti per importo/quantità/carte/ASN/dispositivi (1h/24h/7d).

Segnali comportamentali: geo/fuso orario inadeguato, molte carte/pochi depositi, cache veloce.

5) Routing e cascate PSP

Regole: geo, intervalli BIN, tipo di mappa, costo, conversione, rischio-score.

Cascata: PSP1 → PSP2 in caso di guasto, senza perdita del cestino (idempotent token).

A/B/multi-armed bandit: ottimizzazione della conversione e del costo.

Fail-open/closed - Per errori discutibili, utilizzare il safe-default (ad esempio, ripetizione attraverso un altro merchant), ma non il duble-capture.

6) Contratti API (frammenti di riferimento)

6. 1 Creazione di un intent su un deposito


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 Autorizzazione/Capture


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 Piattaforma web PSP (firmati da )


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"
}

Il ricevitore deve verificare la firma/timestamp/nonce, deduplicare «event _ id», correlare con «intent _ id».

7) Sincronizza con portafoglio (Ledger)

Dopo capture, il comandò wallet. credit '(idipotente) bilancia il giocatore.

Refund: `wallet. debit '(o' wallet. hold _ release 'per void).

Cashout: 'wallet. debit` → `payout` в PSP; dopo il webhook «payout _ settled», chiude la saga.

Saga «deposit»: «authorize» capture «credit», con compensi di rifiuto.

Saga «refund/payout»: «richiest» sottomitted «settled/failed» con ripetizione e deduzione.

8) Ricomposizione - cuore del controllo del denaro

8. 1 Elaborazione giornaliera

Ottieni il report PSP settement (per merchant/data/valuta).

Mappare al registro della piattaforma "intents/captures/refunds/payout's" wallet entries ".

Categorizza:

match: ok, timing: ritardo nei rapporti, missing _ psp: nella piattaforma c'è, in PSP no, missing _ platform: in PSP c'è, nella piattaforma no, amount _ mismatch: differenza di importo/valuta/fee.
Regole auto per timing, ticket/escalation per mismatch.

8. 2 Processo di processo

I rapporti vengono trascinati da SFTP/API pianificati (retrai + controllo integrità).

Parsing → la normalizzazione del mapping → ('psp _ ref', 'intent _ id', 'capture _ id').

Il processo di riconciliazione viene eseguito in OLAP (ClickHouse/BigQuery) per invarianti.

Vetrine BI: conversioni, cause di rifiuto, costo dei canali, orario di chiusura.

8. 3 Alerti

`% mismatch` > X p. p., picco di «missing _ platform», altezza di «amount _ mismatch», deviazione di «deposit _ success» attraverso il canale/geo, aging di transazioni non corrette> N giorni.

9) Chargeback / Dispute

Ciclo di vita: notifica-evidence-representment-arbitration.

Memorizzare i pacchetti evidence (KYC, IP/ASN, device, 3-DS risultati, usage-logs).

Collegamento stretto con risk/anti-fraud: bani di schede/dispositivi/ASN a livello di routing.

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

10) Telemetria e SLO

p95 autorizzazione: 3 c, p99: 6-8 s (dipende da 3-DS/banche).

Deposit success rate per geo/PSP: target dell '85% (riferimento realistico).

Il rapporto è chiuso da T + 1 giorno; aging non corretti

Refund turnaround: ≤ T + 1 per spedizione, ≤ T + 5 per iscrizione (in linea).

Metriche: errato-rate per codice, guasto per 3-DS/AVS, decline-matrix (banca/codice), cost per success, webhook-lag, retry storms.

11) Sicurezza e compliance

mTLS PSP + OAuth2/firma delle richieste; chiavi/certificati per brand/region.

PCI DSS: Tornizzazione PAN, mai memorizzazione CVV, segmentazione zone.

Controllo WORM - Operazioni di crit (manual refund/void, modifica del merchant).

RG/AML: i piedi prima della capture/payout; fogli di sonno/RER; Rapporto SAR/TR.

Residenza PII: fogli/rapporti nella regione; RLS/occultamento in BI.

12) Osservabilità e registrazione

Logi strutturati (JSON) con'trace _ id ',' psp _ ref ',' intent _ id/capture _ id/refund _ id ', codici e lunghezze.

OpenTelemetry HTTP/gRPC/DB/code; 100% di sampling per errori/anomalie monetarie.

Dashboard NOC: conversioni via canale, p95, guasto codice, webhook-lag, DLQ.

13) Pratiche di caos e DR

La caduta di PSP è una macchina/pausa nuova captures.

Ritardo dei webhoop: deadup + ricomposizione attraverso l'API pull.

Out-of-order - Idampotenza e macchina statuaria sulla piattaforma.

Risorsa regionale: asset-passivo/asset-asset, RPO da 5 min, RTO da 30 min.

14) Assegno fogli

Piattaforma/operatore

Tutti i percorsi write con'X-Idempotency-Key ',' X-Trace-ID '.
Routing/cascate PSP con telemetria e limiti.
3-DS/AVS/velocity abilitati; regole risk e ban.
Webhook firmati; Dedotto dì event _ id "; DLQ.
Saghe deposit/refund/payout; rimborso senza «modifiche manuali».
Incrociatura giornaliera T + 1, vetrine mismatch, alert.
Zona PCI, tornitura PAN Controllo WORM delle operazioni di creta.
RG/AML piedi fino a capture/payout.

PSP-integrazione/backend

I contratti di errore sono normalizzati; mapping decline.
Le ripetizioni sono sicure; Le chiavi dell'idipotenza sono documentate.
Time out/retrai/jitter, circuito breaker, rate limits.
I reperti sono disponibili tramite API/SFTP e l'integrità è garantita.

15) Anti-pattern (bandiere rosse)

Il bilanciamento cambia per PSP senza un comando esplicito nel portafoglio.

Nessuna idepotenza. Doppi prelievi/prestiti.

Cassetta integrata all'interno del provider di giochi (perdita del controllo RG/AML/telemetria).

Comuni chiavi merchant per diversi marchi/regioni.

Nessuna mappatura T + 1, mappature Excel manuali.

BI/rapporti regolatori direttamente dalla cassa OLTP.

Gli errori 3-DS/AVS non vengono o analizzati.

Webhook senza firma/convalida della finestra della replica.

Modifica manuale dello stato dei pagamenti/bilanci nel database.

16) Totale

L'integrazione affidabile con i gateway è un'orchestrazione, non un'API ". Il successo garantisce:

1. Comandi e saghe in denaro Idempotent (authorize/capture/refund/payout).

2. Routing e cascate PSP con 3-DS/AVS/velocity e reale telemetria.

3. Incrociatura giornaliera e conteggio rigoroso delle discrepanze.

4. Sicurezza e compilazione (mTLS, firme, PCI, RG/AML, WORM).

Costruendo queste basi, la piattaforma migliora la conversione dei depositi, riduce i rischi di doppie e charjbeek e si sottopone a un controllo sicuro, anche all'apice del traffico e in caso di guasti dei provider esterni.