Integrarea cu gateway-uri de plată: flux, retururi, reconciliere

Articol complet

💡 18+. Material tehnic pentru platformele iGaming, operatori și furnizori de plăți. Nu este un apel pentru a juca.

1) Rolul orchestrării plăților în iGaming

Casa de marcat este „artera” platformei: acceptă depozite, inițiază cashout-uri, procesează retururi/chargeback și se sincronizează cu portofelul (Ledger). O eroare sau o întârziere se transformă rapid în risc financiar și de conformitate. Sarcina arhitecturii este fluxul de numerar rapid și probabil corect în cazul oricăror eșecuri.

2) Fluxul de bază cu PSP (harta de stat)

2. 1 Depozit (card de stare)

1. create_intent (INIȚIAT) → Creați o intenție de plată pe partea platformei.

2. autoriza (AUTORIZAT) → dețină în PSP (opțional - captura dintr-o dată).

3. cârlige 3-DS/AVS/KYC → controale suplimentare de risc/reglementare.

4. captură (CAPTURED) → debitare; credit portofel.

5. eșuat/expirat/anulat → compensarea și închiderea intenției.

2. 2 Cashout (retragere)

solicitarea validarea .

Confirmări cu patru ochi pentru cantități VIP/mari, limite de viteză și geo-reguli.

2. 3 Gol/Rambursare

anula: anula pentru a captura (deține în afara).

rambursare: returnare parțială/completă după capturare.

Pentru schemele de carduri - statute separate „prezentate/prelucrate”.

Invariant: Adevărul soldului jucătorului este un portofel. Modelele PSP nu modifică în mod direct soldul; numai prin comanda „portofel”. credit/debit "cu idempotenta.

3) Idempotence, chei și retrageri

Fiecare operație de scriere poartă 'X-Idempotency-Key' și 'X-Trace-Id'.

Compoziția cheie este legată de parametrii de afaceri (ex. 'intent _ id + suma + moneda').

Repetarea cu aceeași cheie → același rezultat (200 cu corpul vechi).

Se retrage cu backoff exponențial + jitter, hard 'timeout/deadline'.

4) 3-DS, AVS, viteză, antifraudă

3-DS 2. x: de preferință fluxul de provocare cu amprentarea dispozitivului; Log ECI/CAVV/DSTransID.

AVS/CVV: Includeți codurile de validare în regulile de telemetrie și rutare.

Viteza: limite după cantitate/cantitate/carduri/ASN/dispozitive (1h/24h/7d).

Indicii comportamentale: neconcordanță geo/fus orar, multe carduri/depozite puține, încasări rapide.

5) rutare PSP și cascade

Reguli: geo, intervale BIN, tip card, cost, conversie, rata de risc.

Cascadă: PSP1 → PSP2 pe eșec, fără pierderea coșului (token idempotent).

A/B/bandit multi-armat: optimizarea conversiei și a costurilor.

Fail-open/closed: Pentru erori discutabile, utilizați safe-default (de exemplu, repetați prin alt comerciant), dar nu pentru dublă captură.

6) contracte API (fragmente de referință)

6. 1 Crearea unei intenții de depozit


POST/v1/casier/intentii
Anteturi: X-Idempotency-Key, X-Trace-Id
{
„player_id":"p_123,” „suma „: {„suma”: 50. 00, „valută”: „EUR”}, „metodă”: „card',” metadate „: {” brand _ id': „A”, „regiune”: „EU”}
}
→ 201 {„intent_id":"pi_001,""status":"INITIATED”}

6. 2 Autorizare/Capturare


POST/ v1/cashier/intents/pi_001/authorize
→ 200 {„status „: „AUTORIZAT „, „psp _ ref „:” psp _ aa1”,” eci”:” 05”,” cavv”:”...”}

POST/ v1/cashier/intents/pi_001/capture
→ 200 {„status”: „CAPTURED',” capture _ id': „cap _ 001”}

6. 3 Gol/Rambursare


POST/ v1/cashier/captures/cap_001/refunds
{„refund_id":"rf_001,” „sumă „: {„sumă”: 10. 00, „monedă”:” EUR”}}
→ 202 {„status „: „RAMBURSARE _ TRIMIS”}

6. 4 PSP Webhooks → Platform (semnat de HMAC/EdDSA)


POST/webhooks/psp
Semnătura X: sha256 =...
{
"eveniment ":" plată. capturat „,” psp_ref":"psp_aa1, „intent_id":"pi_001,” „sumă”: {„minor _ unități”: 5000, „valută”: „EUR”}, „occurred_at":"2025-10-23T12:05:01Z,” „idempotency_key":"cap_001”
}

Destinatarul trebuie: să verifice semnătura/marcajul temporal/nonce, să aplice 'event _ id', să se coreleze cu' intent _ id'.

7) Sincronizare cu portofel (Ledger)

După captură: comanda "portofel. credit "(idempotent) → soldul jucătorului.

Rambursare: "portofel. debit „(sau” portofel. hold_release' pentru gol).

Cashout: "portofel. debit '→' payout 'в PSP; după webhook 'payout _ settled' - închiderea saga.

Saga „depozit”: „autoriza → captura → credit” cu compensare pentru eșecuri.

Saga „rambursare/plată”: „cerere → depusă → decontată/eșuată” cu refacere și eliminare a duplicatelor.

8) Reconcilierea - inima controlului banilor

8. 1 Reconciliere zilnică

Obțineți raportul de decontare PSP (prin comerciant/dată/monedă).

Map to platform registry: 'intents/captures/ramburss/payouts' ↔' wallet entries '.

Clasificare:

meci: ok, calendarul: întârziere mіzh rapoarte, missing_psp: în platforma este, în PSP nu este, missing_platform: în PSP este, în platforma nu este, amount_mismatch: discrepanță între suma/moneda/taxa.
Auto-reguli pentru sincronizare, bilete/escaladare pentru nepotrivire.

8. 2 Procesul tehnic

Rapoartele sunt trase de SFTP/API pe un program (retray + control de integritate).

Analizarea normalizării → → cartografierii deterministe ('psp _ ref', 'intent _ id',' capture _ id').

Reconcilierea se efectuează în OLAP (ClickHouse/BigQuery) de către invarianți.

Vitrine BI: conversii, motive pentru eșecuri, costul canalului, ora de închidere.

8. 3 Alerte

„% nepotrivire”> X p. p., „lipsă _ platformă” spike, „sumă _ nepotrivire” creștere, „depozit _ succes” canal/variație geo, îmbătrânirea tranzacțiilor restante> N zile.

9) Chargeback/Litigiu

Ciclul de viață: notificare → dovezi → reprezentare → arbitraj.

Stocați pachete de probe (KYC, IP/ASN, dispozitiv, rezultate 3-DS, jurnale de utilizare).

Relație strânsă cu riscurile/antifraudă: interdicțiile card/dispozitiv/ASN la nivel de rutare.

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

10) Telemetrie și SLO

p95 autorizații: ≤ 3 s, p99: ≤ 6-8 s (depinde de 3-DS/bănci).

Rata de succes a depozitelor prin geo/PSP: țintă ≥ 85% (orientare realistă).

Decalajul de reconciliere: raport închis ≤ T + 1 zi; îmbătrânire neconvertit

Rambursare: ≤ T + 1 pentru trimitere, ≤ T + 5 pentru înscriere (conform schemei).

Metrics: error-rate by codes, failure by 3-DS/AVS, decline-matrix (bank/code), cost per succes, webhook-lag, încercați din nou furtuni.

11) Siguranță și conformitate

mTLS la PSP + OAuth2/request chei de semnături/certificate pe brand/regiune.

PCI DSS: tokenizarea PAN, nu stocați niciodată CVV, segmentarea zonei.

Audit WORM: operațiuni crete (rambursare/anulare manuală, schimbarea comerciantului).

RG/AML: picioare înainte de captare/plată; sanklists/POP; Raportare SAR/STR.

Rezidență PII: jurnale/rapoarte în regiune; RLS/mascare în BI.

12) Observabilitate și exploatare forestieră

Busteni structurati (JSON) cu 'trace _ id',' psp _ ref ',' intent _ id/capture _ id/rambursare _ id', coduri si durate.

OpenTelemetry pe HTTP/gRPC/DB/cozi; 100% eșantionare pentru erori/anomalii monetare.

Tablouri de bord NOC: conversii de canale, p95, eșec cod, webhook-lag, DLQ.

13) Haos-și DR-practici

Căderea PSP: autocascade/” pauză noi capturi„

Întârziere webhooks: deadup + recalibrare prin pull-API.

Out-of-order: idempotency și mașină de stare pe platformă.

Pană regională: activ-pasiv/activ-activ, RPO ≤ 5 min, RTO ≤ 30 min.

14) Liste de verificare

Platformă/Operator

Toate căile de scriere cu "X-Idempotency-Key", "X-Trace-Id'.
PSP rutare/cascade cu telemetrie și limite.
3-DS/AVS/velocity activat; reguli de risc și interdicții.
Webhooks semnat; bunicul prin 'event _ id'; DLQ.
Sagas depozit/rambursare/plată; compensație fără „modificări manuale”.
Zilnic T + 1 reconciliere, cazuri de neconcordanță, alerte.
Zona PCI, tokenizarea PAN; Auditul WORM al operațiunilor crete.
Picioare RG/AML pentru a captura/plăti.

PSP integrare/casierie backend

Contractele de eroare sunt normalizate; cartografierea codurilor de declinare.
Repetările sunt sigure; cheile de idempotabilitate sunt documentate.
Timeouts/retreats/jitter, întrerupător de circuit, limitele ratei.
Rapoartele sunt disponibile prin API/SFTP, integritatea este garantată.

15) Anti-modele (steaguri roșii)

Soldul se modifică prin intermediul webhook-ului PSP fără o comandă explicită în portofel.

Fără idempotență → dublu write-off/credite.

Casa de marcat încorporată în iFrame a furnizorului de jocuri (pierderea controlului RG/AML/telemetrie).

Chei comerciale comune pentru mai multe mărci/regiuni.

Nu T + 1 reconciliere, mapări manuale Excel.

BI/rapoarte de reglementare direct de la biroul de numerar OLTP.

3-DS/AVS erori nu sunt înregistrate/analizate.

Webhooks nesemnate/validarea ferestrei → reluări.

Modificări manuale ale statusurilor de plată/echilibru în baza de date.

16) Linia de jos

Integrarea fiabilă cu gateway-urile de plată este orchestrarea, nu "expedierea API. "Succesul este asigurat de:

1. Comenzi și saga de bani idempotente (autorizare/captură/rambursare/plată).

2. Rutare PSP și cascade cu telemetrie 3-DS/AVS/velocity și reală.

3. Reconcilierea zilnică și contabilizarea strictă a discrepanțelor.

4. Securitate și conformitate (mTLS, semnături, PCI, RG/AML, WORM).

După ce a construit aceste fundații, platforma crește conversia depozitelor, reduce riscurile de luări și chargeback-uri și trece cu încredere auditul - chiar și la vârful traficului și atunci când furnizorii externi eșuează.