Töleg şlýuzlary bilen integrasiýa: flow, yzyna gaýtarmalar, reconciliation

Makalanyň doly teksti

💡 18+. iGaming-platformalar, töleg operatorlary we üpjün edijiler üçin tehniki material. Oýnamaga çagyryş ýok.

1) iGaming-de töleg orkestriniň roly

Kassa - platformanyň "arteriýasy": goýumlary kabul edýär, nagt pullary başlaýar ,/chargeback 'we yzyna gaýtarmalary gaýtadan işleýär we gapjyk (Ledger) bilen sinhronlaşdyrylýar. Bu ýerde ýalňyşlyk ýa-da gijä galmak çalt maliýe we laýyk töwekgelçilige öwrülýär. Arhitekturanyň wezipesi - islendik şowsuzlyklarda çalt we subut edilip bilinjek dogry pul akymy.

2) PSP bilen esasy flow (ýagdaý kartasy)

2. 1 Goýum (ýagdaýlar kartasy)

1. create_intent (INITIATED) → platforma tarapynda töleg niýetini döretmek.

2. authorize (AUTHORIZED) → PSP hold (goşmaça - derrew capture).

3. 3-DS/AVS/KYC hooks → goşmaça töwekgelçilik/düzgünleşdiriji barlaglar.

4. capture (CAPTURED) → serişdeleri hasapdan çykarmak; credit gapjygy.

5. failed/expired/canceled → kompensasiýa we intentiň ýapylmagy.

2. 2 Nagt pul (withdrawal)

request → RG/AML tassyklamalary/çäkleri → payout_initiated → payout_settled/failed.

VIP/uly mukdar üçin "dört gözüň" tassyklamalary, velocity we geo-düzgünleriň çäkleri.

2. 3 Void / Refund

void: capture (hold aýyrýar).

refund: capture-den soň bölekleýin/doly yzyna gaýtarmak.

Kartoçka shemalary üçin - "submitted/processed" aýratyn statuslary.

Invariant: Oýunçynyň balansy boýunça hakykat - gapjyk. PSP-resmileşdirmek balansy gönüden-göni üýtgetmeýär; diňe 'wallet' buýrugy arkaly. credit/debit 'idempotentlik bilen.

3) Idempotentlik, açarlar we retralar

Her write-operasiýa 'X-Idempotency-Key' we 'X-Trace-Id' göterýär.

Açaryň düzümi iş parametrlerine baglydyr (mysal üçin 'intent _ id + amount + currency').

Şol bir açar bilen gaýtalamak → şol bir netije (köne body bilen 200).

Retrailer eksponensial backoff + jitter, gaty 'timeout/deadline'.

4) 3-DS, AVS, velocity, antifrod

3-DS 2. x: has gowusy device-fingerprinting bilen challenge-flow; ECI/CAVV/DSTransID-ni žurnalda saklaň.

AVS/CVV: barlag kodlaryny telemetriýa we routing düzgünlerine goşuň.

Velocity: jemi/sany/kartoçkalar/ASN/enjamlar boýunça çäkler (1h/24h/7d).

Özüni alyp baryş signallary: geo/sagat zolagynyň gabat gelmezligi, köp kartoçka/az depozit, çalt kesşautlar.

5) Marşrut we PSP kaskadlary

Düzgünler: geo, BIN-diapazonlar, kartyň görnüşi, bahasy, öwrülişigi, töwekgelçilik-skor.

Kaskad: PSP1 → PSP2 ret edilende, sebet ýitirilmezden (idempotent token).

A/B/multi-armed bandit: öwrülişigi we bahasyny optimizirlemek.

Fail-open/closed: şübheli ýalňyşlyklar üçin safe-default (mysal üçin, başga bir söwda arkaly gaýtalamak) ulanyň, ýöne duble-capture üçin däl.

6) API şertnamalary (salgylanma bölekleri)

6. 1 Goýumda intentiň döredilmegi


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 Ygtyýarnama/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 PSP → platforma webhuklary (HMAC/EdDSA tarapyndan gol çekilýär)


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

Kabul ediji: goly/taýtstampy/nonce barlamaga, 'event _ id' -ni duplizirlemäge, 'intent _ id' -ni baglanyşdyrmaga borçludyr.

7) Gapjyk bilen sinhronlamak (Ledger)

capture: 'wallet. credit '(idempotent) → oýunçynyň balansy.

Refund: `wallet. debit '(ýa-da' wallet. hold_release' void üçin).

Keshaut: 'wallet. debit` → `payout` в PSP; webhukdan soň 'payout _ settled' - saga ýapylýar.

Saga "deposit": 'authorize → capture → credit' ret edilende öwezini dolmak bilen.

"refund/payout" saga: 'request → submitted → settled/failed'

8) Reconciliation (deňeşdirme) - pul gözegçiliginiň ýüregi

8. 1 Gündelik deňeşdirme

PSP settlement report (söwda/sene/walýuta boýunça).

Platformanyň sanawy bilen deňeşdiriň: 'intents/captures/refunds/payouts' 'wallet entries'.

Kategoriýalaşdyrmak:

match: hemme zat gowy, timing: hasabatlaryň arasynda gijä galmak, missing_psp: platformada bar, PSP-de ýok, missing_platform: PSP-de bar, platformada ýok, amount_mismatch: pul/walýuta/fee tapawudy.
Timing üçin awto-düzgünler, mismatch üçin biletler/eskalasiýa.

8. 2 Tehniki proses

Hasabatlar SFTP/API tarapyndan meýilnama boýunça çekilýär (retralar + bitewilik gözegçiligi).

Parsing → kadalaşma → kesgitlenen mapping ('psp _ ref', 'intent _ id', 'capture _ id').

Deňeşdirme OLAP-da (ClickHouse/BigQuery) üýtgewsiz ýerine ýetirilýär.

BI vitrinleri: öwrülişikler, şowsuzlyklaryň sebäpleri, kanallaryň bahasy, ýapylyş wagty.

8. 3 Alertler

`% mismatch` > X p. p., sıçrama 'missing _ platform', ösüş 'amount _ mismatch', gyşarma 'deposit _ success' kanal/geo, aging ynanylmadyk amallar> N gün.

9) Chargeback / Dispute

Durmuş sikli: notification → evidence → representment → arbitration.

evidence paketlerini saklaň (KYC, IP/ASN, device, 3-DS netijeler, usage-logs).

Töwekgelçilik/anti-fraud bilen ýakyn baglanyşyk: kartlaryň/enjamlaryň/ASN-iň routing derejesinde gadagan edilmegi.

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

10) Telemetriýa we SLO

p95 ygtyýarnama: ≤ 3 s, p99: ≤ 6-8 s (3-DS/banklara bagly).

Deposit success rate geo/PSP: target ≥ 85% (hakyky görkeziji).

Reconciliation lag: Hasabat ýapyk ≤ T + 1 gün; aging ynanmadyklar

Refund turnaround: Ibermek üçin ≤ T + 1, hasaba almak üçin ≤ T + 5 (shema boýunça).

Metrikler: error-rate kodlar boýunça, ret 3-DS/AVS, decline-matrix (bank/kod), cost per success, webhook-lag, retry storms.

11) Howpsuzlyk we gabat gelmek

mTLS PSP + OAuth2/haýyşlaryň gollary; açarlar/sertifikatlar per brand/region.

PCI DSS: PAN tokenizasiýasy, hiç haçan CVV saklamaň, zolaklaryň segmentasiýasy.

WORM-audit: krit-amallar (manual refund/void, merçantyň üýtgemegi).

RG/AML: capture/payout öňündäki aýaklar; sank-listler/PP; SAR/STR hasabat.

PII rezidentlik: sebitdäki girdejiler/hasabatlar; RLS/BI-de gizlemek.

12) Gözegçilik etmek we žurnallaşdyrmak

Gurluşly loglar (JSON) 'trace _ id', 'psp _ ref', 'intent _ id/capture _ id/refund _ id', kodlar we dowamlylyk bilen.

HTTP/gRPC/DB/nobatlarda OpenTelemetry; Hata/pul anomaliýalary üçin 100% sampling.

Daşbordlar NOC: kanallar boýunça konwersiýa, p95, kodlar boýunça şowsuzlyk, webhook-lag, DLQ.

13) Bulam-bujarlyk we DR-amallar

PSP ýykylmagy: awtokaskad/" pause new captures ".

Webhuklaryň gijikdirilmegi: dedup + pull-API arkaly gaýtadan barlamak.

Out-of-order: platformada idempotentlik we status maşyny.

Sebitleýin outage: aktiw-passiw/aktiw-aktiw, RPO ≤ 5 min, RTO ≤ 30 min.

14) Çek-listler

Platforma/operator

'X-Idempotency-Key', 'X-Trace-Id' -den ähli write-ýollar.
Telemetri we çäkleri bolan PSP marşrutlary/kaskadlary.
3-DS/AVS/velocity goşulýar; töwekgelçilik düzgünleri we gadaganlyklar.
Webhuklar gol çekildi; 'event _ id' dap; DLQ.
Sagi deposit/refund/payout; "el düzedişleri" bolmazdan öwezini dolmak.
Gündelik barlamak T + 1, mismatch vitrinleri, aladalar.
PCI zonasy, PAN tokenizasiýasy; WORM-audit girit amallary.
RG/AML aýaklary capture/payout.

Kassanyň PSP integrasiýasy/arkasy

Ýalňyşlyk şertnamalary kadalaşdy; decline kodlary.
Gaýtalanmalar howpsuz; idempotentlik açarlary dokumentleşdirildi.
Wagt-aut/retrai/jitter, circuit breaker, rate limits.
Habarlar API/SFTP arkaly elýeterlidir, bitewiligi kepillendirilýär.

15) Anti-pattern (gyzyl baýdaklar)

Balans PSP webhuk arkaly gapjyga aç-açan buýruk bermezden üýtgeýär.

Biperwaýlyk ýok → goşa hasapdan çykarmak/karzlar.

Oýun üpjün edijisiniň iFrame içindäki içerki kassa (RG/AML/telemetriýa gözegçiligini ýitirmek).

Birnäçe markalara/sebitlere umumy söwda açarlary.

Ýok T + 1 barlamak, Excel el bilen deňeşdirmeler.

BI/düzgünleşdiriji hasabatlar gönüden-göni ALTP kassasyndan.

3-DS/AVS ýalňyşlyklary ýazylmaýar/seljerilmeýär.

Penjiräniň goly/tassyklamasyz webhuklary → repleýler.

DB-de tölegleriň/balanslaryň statuslarynyň el bilen düzedilmegi.

16) Jemleýji

Töleg şlýuzlary bilen ygtybarly integrasiýa "API aralygy" däl-de, orkestrdir. Üstünlik:

1. Idempotent pul buýruklary we saglary (authorize/capture/refund/payout).

2. 3-DS/AVS/velocity we hakyky telemetriýa bilen PSP marşrutlary we kaskadlary.

3. Gündelik deňeşdirme (reconciliation) we gapma-garşylyklary berk hasaba almak.

4. Howpsuzlyk we laýyklyk (mTLS, gollar, PCI, RG/AML, WORM).

Bu esaslary gurup, platforma goýumlaryň konwersiýasyny ýokarlandyrýar, goşa we çarjbekleriň töwekgelçiligini azaldýar we hatda traffigiň iň ýokary derejesinde we daşarky üpjün edijileriň şowsuzlyklarynda-da ynamly auditden geçýär.