Төлем шлюздерімен біріктіру: флоу, қайтарымдар, reconciliation

Мақаланың толық мәтіні

💡 18+. iGaming-платформалар, төлем операторлары мен провайдерлері үшін техникалық материал. Ойынға шақыру емес.

1) iGaming-дегі ақылы оркестрдің рөлі

Касса - платформаның «артериясы»: ол депозиттерді қабылдайды, кэшауттарды бастайды ,/chargeback 'қайтарымдарын өңдейді және әмиянмен (Ledger) үндестіріледі. Бұл жерде қателік немесе кідіріс тез арада қаржылық және комплаенс-тәуекелге айналады. Архитектураның міндеті - кез келген іркілістер кезінде жылдам және дәлелді түрде дұрыс ақша ағыны.

2) PSP базалық флоу (жай-күй картасы)

2. 1 Депозит (жай-күй картасы)

1. create_intent (INITIATED) → платформа жағында төлем ниетін құру.

2. authorize (AUTHORIZED) → PSP холдингі (қосымша - бірден capture).

3. 3-DS/AVS/KYC hooks → тәуекел/реттеуіш бойынша қосымша тексеру.

4. capture (CAPTURED) → қаражатты есептен шығару; credit әмияны.

5. failed/expired/canceled → өтемақы және интентті жабу.

2. 2 Кэшаут (withdrawal)

request → валидация RG/AML/лимиттер → payout_initiated → payout_settled/failed.

VIP/ірі сомалар үшін «төрт көзді» растау, velocity лимиттері және гео-ережелер.

2. 3 Void / Refund

void: capture дейін болдырмау (hold алынады).

refund: capture кейін ішінара/толық қайтару.

Карточкалық схемалар үшін - «submitted/processed» жеке мәртебелері.

Инвариант: Ойыншының балансы бойынша ақиқат - әмиян. PSP-ресімдеу балансты тікелей өзгертпейді; тек 'wallet' пәрмені арқылы. credit/debit 'теңсіздікпен.

3) Іспеттестік, кілттер және ретра

Әрбір write-операцияда 'X-Idempotency-Key' және 'X-Trace-Id' болады.

Кілттің композициясы бизнес параметрлеріне байланыстырылған (мысалы, 'intent _ id + amount + currency').

Сол кілтпен қайталау → сол нәтиже (ескі body бар 200).

Экспоненциалды backoff + джиттер, қатқыл 'timeout/deadline'.

4) 3-DS, AVS, velocity, антифрод

3-DS 2. x: негізінен device-fingerprinting бар challenge-flow; журналда ECI/CAVV/DSTransID сақтаңыз.

AVS/CVV: тексеру кодтарын телеметрияға және роутинг ережелеріне қосыңыз.

Velocity: сомасы/саны/карталары/ASN/құрылғылары бойынша лимиттер (1h/24h/7d).

Мінез-құлық сигналдары: гео/сағат белдеуінің сәйкессіздігі, көптеген карталар/аз депозиттер, жылдам кэшауттар.

5) Роутинг және PSP каскадтары

Ережелер: гео, BIN-диапазондар, карта түрі, құны, конверсия, тәуекел-скор.

Каскад: PSP1 → PSP2 бас тартқан кезде себетті жоғалтпастан (idempotent token).

A/B/multi-armed bandit: конверсия мен құнды оңтайландыру.

Fail-open/closed: күмәнді қателер үшін safe-default (мысалы, басқа мерчант арқылы қайталау) қолданыңыз, бірақ duble-capture үшін қолданбаңыз.

6) API келісімшарттары (эталондық фрагменттер)

6. 1 Депозитте интент құру


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 Авторизация/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 → платформа вебхуттары (HMAC/EdDSA қол қойған)


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

Қабылдағыш: қолтаңбаны/таймштампты/nonce тексеруге, 'event _ id' дегенді дедуплициялауға, 'intent _ id' дегенді байланыстыруға міндетті.

7) Әмиянмен үндестіру (Ledger)

capture кейін: 'wallet пәрмені. credit '(іспеттес) → ойыншының балансы.

Refund: `wallet. debit '(немесе' wallet. hold_release' void үшін).

Кэшаут: 'wallet. debit` → `payout` в PSP; вебхуктен кейін 'payout _ settled' - сағаны жабу.

Сага «deposit»: 'authorize → capture → credit' бас тартқан кезде өтемақымен.

«refund/payout» дастаны: 'request → submitted → settled/failed' қайталауы мен атасымен.

8) Reconciliation (салыстыру) - ақшаны бақылау жүрегі

8. 1 Күнделікті салыстыру

PSP settlement report алу (мерчант/күні/валютасы бойынша).

Платформаның тізілімімен салыстыру: 'intents/captures/refunds/payouts' 'wallet entries'.

Санат:

match: бәрі жақсы, timing: есептер арасында кідіріс, missing_psp: платформада бар, PSP жоқ, missing_platform: PSP бар, платформада жоқ, amount_mismatch: сома/валюта/fee айырмашылығы.
Timing үшін авто-ережелер, mismatch үшін тикеттер/эскалациялар.

8. 2 Техникалық процесс

Есептер SFTP/API кестесі бойынша созылады (ретрайлер + тұтастық бақылауы).

Парсинг → қалыпқа келтіру → детерминирленген маппинг ('psp _ ref', 'intent _ id', 'capture _ id').

Салыстырып тексеру OLAP-те (ClickHouse/BigQuery) инварианттар бойынша орындалады.

BI сөрелері: конверсиялар, істен шығу себептері, арналар құны, жабылу уақыты.

8. 3 Алерттар

`% mismatch` > X p. p., өскін 'missing _ platform', өсу 'amount _ mismatch', ауытқу 'deposit _ success' арнасы бойынша/geo, aging аударылмаған транзакциялар> N күн.

9) Chargeback / Dispute

Өмірлік цикл: notification → evidence → representment → arbitration.

evidence-пакеттерді сақтаңыз (KYC, IP/ASN, device, 3-DS нәтижелер, usage-логи).

Тәуекелмен/anti-fraud тығыз байланыс: карта/құрылғы/ASN тыйым салу.

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

10) Телеметрия және SLO

p95 авторизациялау: ≤ 3 с, p99: ≤ 6-8 с (3-DS/банктерге байланысты).

Deposit success rate гео/PSP бойынша: таргет ≥ 85% (шынайы бағдар).

Reconciliation lag: есеп жабық ≤ T + 1 күн; сенім артылмаған

Refund turnaround: жөнелтуге ≤ T + 1, есепке алуға ≤ T + 5 (схема бойынша).

Өлшемдер: кодтар бойынша error-rate, 3-DS/AVS бойынша бас тарту, decline-matrix (банк/код), cost per success, webhook-lag, retry storms.

11) Қауіпсіздік және комплаенс

mTLS PSP + OAuth2/сұрау қолтаңбасына; per brand/region кілттері/куәліктері.

PCI DSS: PAN токенизациялау, ешқашан CVV сақтау, сегменттеу аймақтары.

WORM-аудит: крит-операциялар (manual refund/void, мерчанттың өзгеруі).

RG/AML: capture/payout алдындағы табандар; санк-парақтар/РЕР; SAR/STR есептілігі.

PII резиденттігі: өңірдегі логи/есептер; RLS/BI жасыру.

12) Бақылау және журналға түсіру

Құрылымдалған логтар (JSON) 'trace _ id', 'psp _ ref', 'intent _ id/capture _ id/refund _ id', кодтармен және ұзақтықтармен.

OpenTelemetry HTTP/gRPC/DB/кезектерінде; Қателер/ақшалай ауытқулар үшін 100% сэмплинг.

NOC дашбордтары: арналар бойынша конверсиялар, p95, кодтар бойынша бас тарту, webhook-lag, DLQ.

13) Хаос және DR-практикалар

PSP құлауы: автокаскад/« pause new captures ».

Вебхуктардың кідіруі: дедуп + pull-API арқылы қайта салыстыру.

Out-of-order: платформадағы идемпотенттілік және мәртебе машинасы.

Өңірлік outage: актив-пассив/актив-актив, RPO ≤ 5 мин, RTO ≤ 30 мин.

14) Чек парақтары

Платформа/оператор

Барлық write-жолдары 'X-Idempotency-Key', 'X-Trace-Id'.
Телеметриясы және лимиттері бар PSP роутингі/каскадтары.
3-DS/AVS/velocity қосылған; тәуекел-ережелер мен тыйымдар.
Вебхактар қол қойды; дедуп бойынша 'event _ id'; DLQ.
Саги deposit/refund/payout; «қолмен түзетулерсіз» өтемақы.
Күнделікті салыстыру T + 1, сөрелер mismatch, алерта.
PCI аймағы, PAN токенизациясы; WORM-аудит крит-операциялары.
RG/AML табан capture/payout дейін.

PSP интеграциясы/кассалық бэкенд

Қателер келісімшарттары қалыпқа келтірілді; decline-кодтардың маппингі.
Қайталаулар қауіпсіз; сәйкестілік кілттері құжатталған.
Тайм-ауттар/ретраи/джиттер, circuit breaker, rate limits.
Репорттар API/SFTP бойынша қол жетімді, тұтастығына кепілдік беріледі.

15) Қарсы үлгілер (қызыл жалаулар)

Теңгерім PSP вебхугында анық әмиянға пәрменсіз өзгереді.

Екі есе есептен шығару/кредиттер жоқ.

Ойын провайдерінің iFrame ішіндегі кіріктірілген касса (RG/AML/телеметрия бақылауын жоғалту).

Бірнеше брендтерге/өңірлерге ортақ мерчант-кілттер.

Жоқ T + 1 салыстыру, Excel қолмен салыстыру.

BI/реттегіш есептер тікелей OLTP кассасынан.

3-DS/AVS қателері талданбайды.

Терезенің қолтаңбасы/валидациясы жоқ вебхактар → реплеялар.

Төлемдер/баланстар мәртебелерін ДҚ-да қолмен түзету.

16) Жиынтық

Төлем шлюздерімен сенімді интеграция - бұл «API жүгірісі» емес, оркестрлеу. Табысты қамтамасыз етеді:

1. Идемпотенттік ақша командалары мен сағаттары (authorize/capture/refund/payout).

2. 3-DS/AVS/velocity және нақты телеметриясы бар PSP роутингі мен каскадтары.

3. Күнделікті салыстыру (reconciliation) және айырмашылықтарды қатаң есепке алу.

4. Қауіпсіздік және комплаенс (mTLS, қолтаңбалар, PCI, RG/AML, WORM).

Осы негіздерді құра отырып, платформа депозиттердің конверсиясын арттырады, дубльдер мен чарджбектердің тәуекелдерін төмендетеді және тіпті трафиктің шыңында және сыртқы провайдерлердің істен шығуы кезінде де аудиттен сенімді түрде өтеді.