Ödəniş şlüzləri ilə inteqrasiya: flow, geri qaytarmalar, reconciliation

Məqalənin tam mətni

💡 18+. iGaming platformaları, ödəniş operatorları və provayderləri üçün texniki material. Oyuna çağırış deyil.

1) iGaming-də ödəniş orkestrinin rolu

Kassa - platformanın «arteriyası»: o, depozitləri qəbul edir, cashautları işə salır ,/chargeback 'və pul kisəsi ilə sinxronlaşdırılır (Ledger). Burada səhv və ya gecikmə tez bir zamanda maliyyə və uyğunluq riskinə çevrilir. Arxitekturanın vəzifəsi hər hansı bir nasazlıqda sürətli və sübut edilə bilən düzgün pul axınıdır.

2) PSP ilə əsas flow (vəziyyət xəritəsi)

2. 1 Depozit (hallar kartı)

1. create_intent (INITIATED) → platforma tərəfində ödəniş niyyəti yaratmaq.

2. authorize (AUTHORIZED) → PSP hold (isteğe bağlı - dərhal capture).

3. 3-DS/AVS/KYC hooks → əlavə risk yoxlama/tənzimləyici.

4. capture (CAPTURED) → vəsaitlərin silinməsi; cüzdan kredit.

5. failed/expired/canceled → kompensasiya və intent bağlanması.

2. 2 Cashout (withdrawal)

request → validasiya RG/AML/limitləri → payout_initiated → payout_settled/failed.

VIP/böyük məbləğlər üçün «dörd göz» təsdiqləri, velocity limitləri və geo-qaydalar.

2. 3 Void / Refund

void: capture əvvəl ləğv (hold çıxarır).

refund: capture sonra qismən/tam qaytarılması.

Kart sxemləri üçün - ayrı statuslar «submitted/processed».

İnvariant: Oyunçunun balansında həqiqət pul kisəsidir. PSP rəsmiləşdirmələri birbaşa balansı dəyişmir; yalnız 'wallet əmri vasitəsilə. idempotentlik ilə credit/debit '.

3) İdempotentlik, açarlar və retralar

Hər bir write-əməliyyat 'X-Idempotency-Key' və 'X-Trace-Id' daşıyır.

Açarın kompozisiyası biznes parametrlərinə bağlıdır (məsələn, 'intent _ id + amount + currency').

Eyni açar ilə təkrar → eyni nəticə (köhnə body ilə 200).

Retrailer eksponensial backoff + jitter, sərt 'timeout/deadline'.

4) 3-DS, AVS, velocity, antifrod

3-DS 2. x: device-fingerprinting ilə üstünlük challenge-flow; ECI/CAVV/DSTransID-ni jurnalda saxlayın.

AVS/CVV: Telemetriyada yoxlama kodlarını və marşrut qaydalarını daxil edin.

Velocity: məbləğ/miqdar/kart/ASN/qurğular üzrə limitlər (1h/24h/7d).

Davranış siqnalları: geo/saat kəmərinin uyğunsuzluğu, çox kart/az depozit, sürətli cashautlar.

5) Marşrutlaşdırma və PSP kaskadları

Qaydalar: geo, BIN diapazonları, kart növü, dəyəri, dönüşüm, risk-skor.

Kaskad: PSP1 → PSP2 uğursuz olduqda, səbəti itirmədən (idempotent token).

A/B/multi-armed bandit: dönüşüm və dəyəri optimallaşdırma.

Fail-open/closed: şübhəli səhvlər üçün safe-default (məsələn, başqa bir satıcı vasitəsilə təkrar) tətbiq edin, lakin duble-capture üçün deyil.

6) API müqavilələri (istinad fraqmentləri)

6. 1 Depozitdə intentin yaradılması


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 Authorization/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 vebhukları (HMAC/EdDSA tərəfindən imzalanmışdı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"
}

Qəbuledici tələb olunur :/taymstamp/nonce imzasını yoxlamaq, 'event _ id' deduplication, 'intent _ id' ilə korrelyasiya etmək.

7) Cüzdan ilə sinxronizasiya (Ledger)

capture sonra: 'wallet əmri. credit '(idempotent) → oyunçu balans.

Refund: `wallet. debit '(və ya' wallet. hold_release' void üçün).

Cashout: 'wallet. debit` → `payout` в PSP; 'payout _ settled' vebhukundan sonra - dastanın bağlanması.

«Deposit» dastanı: 'authorize → capture → credit' uğursuzluqlar üçün kompensasiya ilə.

«refund/payout» dastanı: 'request → submitted → settled/failed' təkrarla və dedupla.

8) Reconciliation - pul nəzarət ürək

8. 1 Gündəlik yoxlama

PSP settlement report almaq (alış-veriş/tarix/valyuta).

Platformanın reyestri ilə müqayisə edin: 'intents/captures/refunds/payouts' 'wallet entries'.

Kateqoriya:

match: tamam, timing: hesabatlar arasında gecikmə, missing_psp: platformada var, PSP-də yoxdur, missing_platform: PSP-də var, platformada yoxdur, amount_mismatch: məbləğ/valyuta/fee fərqi.
timing üçün avto qaydaları, mismatch üçün biletlər/eskalasiya.

8. 2 Texniki proses

Hesabatlar SFTP/API cədvəlinə görə uzanır (retralar + bütövlük nəzarəti).

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

Müqayisə OLAP-da (ClickHouse/BigQuery) invariantlar üzrə aparılır.

BI vitrinləri: dönüşüm, nasazlıq səbəbləri, kanal dəyəri, bağlanış vaxtı.

8. 3 Alertlər

`% mismatch` > X p. p., sıçrayış 'missing _ platform', artım 'amount _ mismatch', kənarlaşma 'deposit _ success' kanal/geo, aging səhv əməliyyatlar> N gün.

9) Chargeback / Dispute

Həyat dövrü: notification → evidence → representment → arbitration.

evidence paketləri (KYC, IP/ASN, device, 3-DS nəticələr, usage-logs) saxlayın.

Risk/anti-fraud ilə sıx əlaqə: kart/cihaz/ASN routing səviyyəsində qadağan.

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

10) Telemetriya və SLO

p95 avtorizasiya: ≤ 3 s, p99: ≤ 6-8 s (3-DS/banklardan asılıdır).

Deposit success rate geo/PSP: hədəf ≥ 85% (real istinad).

Reconciliation lag: hesabat bağlandı ≤ T + 1 gün; aging etibarsız

Refund turnaround: Göndərmə üçün ≤ T + 1, qəbul üçün ≤ T + 5 (sxem üzrə).

Metriklər: error-rate kodları, 3-DS/AVS imtinası, decline-matrix (bank/kod), cost per success, webhook-lag, retry storms.

11) Təhlükəsizlik və uyğunluq

mTLS PSP + OAuth2/sorğu imzaları; açarları/sertifikatları per brand/region.

PCI DSS: PAN tokenizasiya, heç vaxt CVV saxlamaq, seqmentasiya zonaları.

WORM-audit: krit əməliyyatları (manual refund/void, merchant dəyişikliyi).

RG/AML: capture/payout qarşısında ayaq; sank-list/RER; SAR/STR hesabat.

PII rezidentlik: regionda log/hesabatlar; BI RLS/maskalama.

12) Müşahidə və jurnallaşdırma

Strukturlaşdırılmış loglar (JSON) 'trace _ id', 'psp _ ref', 'intent _ id/capture _ id/refund _ id', kodlar və uzunluqlarla.

OpenTelemetry HTTP/gRPC/DB/növbələrdə; 100% səhvlər/pul anomaliyaları üçün sampling.

NOC dashbordları: kanallar, p95, kodlar, webhook-lag, DLQ.

13) Xaos və DR təcrübələri

PSP düşməsi: avtokaskad/« pause new captures ».

Gecikmiş vebhuk: dedup + pull-API vasitəsilə yenidən yoxlama.

Out-of-order: platformada idempotentlik və status maşın.

Regional outage: aktiv-passiv/aktiv-aktiv, RPO ≤ 5 dəq, RTO ≤ 30 dəq.

14) Çek vərəqləri

Platforma/operator

'X-Idempotency-Key', 'X-Trace-Id' ilə bütün write yolları.
Telemetriya və limitlərlə PSP marşrutu/kaskadları.
3-DS/AVS/velocity daxildir; risk-qaydaları və qadağan.
Webhucks imzalanmışdır; dedup 'event _ id'; DLQ.
Saqi deposit/refund/payout; «əl düzəlişləri» olmadan kompensasiya.
T + 1 gündəlik yoxlama, mismatch vitrinləri, alertlər.
PCI zonası, PAN tokenizasiyası; WORM-audit krit əməliyyatları.
RG/AML ayaq capture/payout.

PSP inteqrasiya/arxa kassa

Səhv müqavilələri normallaşdırılır; decline kodları mapping.
Təkrar təhlükəsiz; idempotentlik açarları sənədləşdirilmişdir.
Time-out/retrai/jitter, circuit breaker, rate limits.
Reports API/SFTP mövcuddur, bütövlüyü təmin edilir.

15) Anti-nümunələr (qırmızı bayraqlar)

Balans PSP vebhuk vasitəsilə cüzdana açıq əmr olmadan dəyişir.

Heç bir idempotentlik → ikiqat debet/kreditlər.

Oyun provayderi iFrame daxilində daxili kassa (RG/AML/telemetriya nəzarəti itkisi).

Bir neçə marka/regionda ümumi ticarət açarları.

T + 1 yoxluğu, əl Excel müqayisə.

BI/tənzimləyici hesabatlar birbaşa ALTP kassa.

Səhvlər 3-DS/AVS/təhlil edilmir.

Vebhuka imzasız/validasiya pəncərə → replay.

DB-də ödəniş/balans statuslarının əl ilə düzəldilməsi.

16) Yekun

Ödəniş şlüzləri ilə etibarlı inteqrasiya «API keçid» deyil, orkestrasiyadır. Müvəffəqiyyət təmin edir:

1. İdempotent pul komandaları və dastanları (authorize/capture/refund/payout).

2. 3-DS/AVS/velocity və real telemetriya ilə PSP marşrutu və kaskadları.

3. Gündəlik yoxlama (reconciliation) və ciddi uyğunsuzluq uçotu.

4. Təhlükəsizlik və uyğunluq (mTLS, imzalar, PCI, RG/AML, WORM).

Bu əsasları qurmaqla platforma depozitlərin konvertasiyasını artırır, ikiqat və çarjbeklərin risklərini azaldır və hətta trafikin zirvəsində və xarici provayderlərin uğursuzluqları zamanı etibarlı auditdən keçir.