Toʻlov shlyuzlari bilan integratsiya: flow, qaytarish, reconciliation

Maqolaning to’liq matni

💡 18+. iGaming-platformalar, to’lov operatorlari va provayderlari uchun texnik material. O’yinga chaqirish emas.

1) iGaming’da to’lov orkestrining roli

Kassa - platformaning «arteriyasi»: u depozitlarni qabul qiladi, keshautlarni boshlaydi ,/chargeback’va qaytarmalarni qayta ishlaydi va hamyon (Ledger) bilan sinxronlashtiriladi. Bu yerda xato yoki kechikish tezda moliyaviy va komplayens xavfga aylanadi. Arxitekturaning vazifasi - har qanday nosozliklarda tezkor va aniq pul oqimi.

2) PSP bilan bazaviy flou (holatlar xaritasi)

2. 1 Depozit (holatlar xaritasi)

1. create_intent (INITIATED) → platforma tomonida to’lov niyatini yaratish.

2. authorize (AUTHORIZED) → PSP hold (ixtiyoriy ravishda - darhol capture).

3. 3-DS/AVS/KYC hooks → tavakkalchilik/tartibga solish bo’yicha qo’shimcha tekshiruvlar.

4. capture (CAPTURED) → mablag’larni hisobdan chiqarish; credit hamyoni.

5. failed/expired/canceled → kompensatsiya va intentni yopish.

2. 2 Keshaut (withdrawal)

request → validatsiya RG/AML/limitlar → payout_initiated → payout_settled/failed.

VIP/katta summalar uchun «to’rt ko’z» ni tasdiqlash, velocity limitlari va geo-qoidalar.

2. 3 Void / Refund

void: capture dan oldin bekor qilish (hold ni olib tashlaydi).

refund: capture dan keyin qisman/to’liq qaytarish.

Kartochka sxemalari uchun - alohida «submitted/processed» maqomlari.

Invariant: O’yinchining balansi bo’yicha haqiqat - hamyon. PSP-rasmiylashtirish to’g «ridan to’g» ri balansni o’zgartirmaydi; faqat’wallet’buyrugʻi orqali. credit/debit’s idempotentlik.

3) Idempotentlik, kalitlar va retralar

Har bir write-operatsiya’X-Idempotency-Key’va’X-Trace-Id’ni olib yuradi.

Kalit kompozitsiyasi biznes parametrlariga bogʻlangan (masalan,’intent _ id + amount + currency’).

Bir xil kalit bilan takrorlash → bir xil natija (eski body bilan 200).

Retrajlar eksponensial backoff + jitter, qattiq’timeout/deadline’.

4) 3-DS, AVS, velocity, antifrod

3-DS 2. x: ko’proq device-fingerprinting bilan challenge-flow; ECI/CAVV/DSTransID’ni jurnalda saqlang.

AVS/CVV: tekshirish kodlarini telemetriya va routing qoidalariga kiriting.

Velocity: summa/miqdor/kartalar/ASN/qurilmalar bo’yicha limitlar (1h/24h/7d).

Xulq-atvor signallari: geo/soat mintaqasining nomuvofiqligi, ko’p kartalar/kam depozitlar, tezkor keshautlar.

5) Routing va PSP kaskadlari

Qoidalar: geo, BIN-diapazonlar, kartaning turi, qiymati, konvertatsiyasi, tavakkalchilik-tezligi.

Kaskad: PSP1 → PSP2 rad etilganda, savatsiz (idempotent token).

A/B/multi-armed bandit: konversiya va qiymatni optimallashtirish.

Fail-open/closed: shubhali xatolar uchun safe-default (masalan, boshqa sotuvchi orqali takrorlash) dan foydalaning, lekin duble-capture uchun emas.

6) API kontraktlari (etalon parchalari)

6. 1 Depozitda intent yaratish


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 Avtorizatsiya/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 Vebxuklar PSP → platforma (HMAC/EdDSA tomonidan imzolangan)


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

Qabul qilgich quyidagilarga majbur: imzoni/taymshtampni/nonce tekshirish, «event _ id» deduplizatsiya qilish, «intent _ id» bilan bogʻlash.

7) Hamyon bilan sinxronlashtirish (Ledger)

Capture:’wallet. credit’(idempotentno) → o’yinchining balansi.

Refund: `wallet. debit’(yoki’wallet. hold_release' void uchun).

Keshaut:’wallet. debit` → `payout` в PSP; vebxukdan keyin’payout _ settled’- dastani yopish.

Saga «deposit»:’authorize → capture → credit’rad etilganda kompensatsiya bilan.

«refund/payout»:’request → submitted → settled/failed’saga aylantirish va bobosi bilan.

8) Reconciliation (solishtirish) - pulni nazorat qilish yuragi

8. 1 Har kuni solishtirish

PSP settlement report olish (savdo/sana/valyuta bo’yicha).

Platforma reyestri bilan taqqoslash:’intents/captures/refunds/payouts’ ’wallet entries’.

Quyidagilarni toifalash:

match: hammasi yaxshi, timing: hisobotlar o’rtasida kechikish, missing_psp: platformada bor, PSPda yo’q, missing_platform: PSPda bor, platformada yo’q, amount_mismatch: summa/valyuta/fee tafovuti.
Timing uchun avto qoidalar, mismatch uchun tiketlar/eskalatsiyalar.

8. 2 Texnik jarayon

Hisobotlar jadval boʻyicha SFTP/APIga tortiladi (retralar + yaxlitlik nazorati).

Parsing → normallashtirish → determinirlangan mapping (’psp _ ref’,’intent _ id’,’capture _ id’).

Solishtirish invariantlar boʻyicha OLAP (ClickHouse/BigQuery) da amalga oshiriladi.

BI vitrinalari: konversiyalar, nosozliklar sabablari, kanallar narxi, yopilish vaqti.

8. 3 Alertlar

`% mismatch` > X p. p., shov-shuv’missing _ platform’, o’sish’amount _ mismatch’, kanal/geo, aging bo’yicha’deposit _ success’ning og’ishi> N kun.

9) Chargeback / Dispute

Hayot sikli: notification → evidence → representment → arbitration.

evidence paketlarini (KYC, IP/ASN, device, 3-DS natijalar, usage-loglar) saqlang.

Risk/anti-fraud bilan yaqin aloqa: xarita/qurilma/ASN taqiqlari routing darajasida.

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

10) Telemetriya va SLO

p95 avtorizatsiya: ≤ 3 s, p99: ≤ 6-8 s (3-DS/banklarga bog’liq).

Deposit success rate geo/PSP bo’yicha: target ≥ 85% (realistik mo’ljal).

Reconciliation lag: hisobot yopiq ≤ T + 1 kun; aging soddalashtirilmagan

Refund turnaround: jo’natish uchun ≤ T + 1, qabul qilish uchun ≤ T + 5 (sxema bo’yicha).

Metriklar: kodlar bo’yicha error-rate, 3-DS/AVS bo’yicha rad etish, decline-matrix (bank/kod), cost per success, webhook-lag, retry storms.

11) Xavfsizlik va komplayens

mTLS PSP + OAuth2/so’rovlar imzosiga; kalitlar/sertifikatlar per brand/region.

PCI DSS: PAN tokenlash, hech qachon CVV saqlanmaydi, zonalar segmentatsiyasi.

WORM-audit: krit-operatsiyalar (manual refund/void, merchantning o’zgarishi).

RG/AML: capture/payout oldidagi oyoqlar; sank-listы/PER; SAR/STR hisoboti.

PII rezidentlik: mintaqadagi logi/hisobotlar; RLS/BI maskalash.

12) Kuzatish va jurnalga olish

Tuzilgan loglar (JSON)’trace _ id’,’psp _ ref’,’intent _ id/capture _ id/refund _ id’, kodlar va davomiyliklar bilan.

OpenTelemetry HTTP/gRPC/DB/navbatlarda; Xato/pul anomaliyalari uchun 100% sampling.

NOC dashbordlari: kanallar bo’yicha konversiyalar, p95, kodlar bo’yicha rad etish, webhook-lag, DLQ.

13) Xaos va DR amaliyotlari

PSP qulashi: avtokaskad/« pause new captures ».

Vebxuklarni kechiktirish: dedup + pull-API orqali qayta solishtirish.

Out-of-order: platformada idempotentlik va maqom mashinasi.

Mintaqaviy outage: aktiv-passiv/aktiv-aktiv, RPO ≤ 5 min., RTO ≤ 30 min.

14) Chek-varaqlar

Platforma/operator

Barcha write-yo’llar’X-Idempotency-Key’,’X-Trace-Id’bilan.
Telemetriya va limitlar bilan PSPning routing/kaskadlari.
3-DS/AVS/velocity kiritilgan; risk-qoidalar va taqiqlar.
Vebxuklar imzolangan; ’event _ id’ bo’yicha dedup; DLQ.
Sagi deposit/refund/payout; «qo’lda tuzatishlarsiz» kompensatsiyalar.
Kundalik T + 1 taqqoslash, mismatch vitrinalari, alertlar.
PCI-zona, PAN tokenizatsiyasi; Krit operatsiyalarining WORM auditi.
RG/AML oyoqlari capture/payout gacha.

PSP integratsiyasi/kassaning orqa tomoni

Xato shartnomalari normallashtirilgan; decline-kodlarning mappingi.
Takrorlash xavfsiz; idempotentlik kalitlari hujjatlashtirilgan.
Taym-autlar/retrajlar/jitter, circuit breaker, rate limits.
Reportlar API/SFTP orqali mavjud, yaxlitligi kafolatlanadi.

15) Anti-patternlar (qizil bayroqlar)

Balans aniq buyruqsiz PSP vebxukiga o’zgaradi.

Idempotentlik yo’q → ikki marta hisobdan chiqarish/kreditlar.

O’yinlar provayderining iFrame ichidagi ichki kassa (RG/AML/telemetriya nazoratini yo’qotish).

Bir nechta brend/mintaqalarga umumiy savdo kalitlari.

Yo’q T + 1 solishtirmalar, qo’lda Excel-taqqoslashlar.

BI/regulyator hisobotlari to’g’ridan-to’g’ri OLTP kassasidan.

Xatolar 3-DS/AVS tahlil qilinmaydi.

Imzosiz/validatsiyasiz vebxuklar

DBda to’lovlar/balanslar maqomlarini qo’lda tuzatish.

16) Jami

To’lov shlyuzlari bilan ishonchli integratsiya - bu «API o’tish» emas, balki orkestr. Muvaffaqiyat quyidagilarni ta’minlaydi:

1. Idempotent pul buyruqlari va dostonlari (authorize/capture/refund/payout).

2. 3-DS/AVS/velocity va real telemetriyali PSP routing va kaskadlari.

3. Har kuni taqqoslash (reconciliation) va tafovutlarni qatʼiy hisobga olish.

4. Xavfsizlik va komplayens (mTLS, imzolar, PCI, RG/AML, WORM).

Ushbu asoslarni qurish orqali platforma depozitlar konvertatsiyasini oshiradi, dubllar va chorjbeklar xavfini kamaytiradi va hatto trafikning eng yuqori choʻqqisida va tashqi provayderlarning nosozliklarida ham ishonchli auditdan oʻtadi.