Төлөм шлюздары менен интеграция: флоу, кайтарымдар, reconciliation

Макаланын толук тексти

💡 18+. iGaming платформалары, операторлор жана төлөм провайдерлери үчүн техникалык материал. оюнга чакыруу эмес.

1) iGaming төлөм оркестринин ролу

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

2) PSP менен негизги Flow (абалы карта)

2. 1 Депозит (шарттар картасы)

1. create_intent (INITIATED) → платформа тарабында төлөм ниетин түзүү.

2. authorize (AUTHORIZED) → PSP (кошумча - дароо колго).

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

Invariant: оюнчу балансы боюнча чындык - капчык. PSP-жол-жоболоштуруу түздөн-түз балансты өзгөртө албайт; Кошелек командасы аркылуу гана. credit/debit 'демпотенттик менен.

3) Идемпотенттүүлүк, ачкычтар жана ретра

Ар бир write операциясы 'X-Idempotency-Key' жана 'X-Trace-Id'.

Ачкычтын курамы бизнес параметрлерине байланыштуу (мисалы, 'intent _ id + amount + currency').

Ошол эле ачкыч менен кайталоо → ошол эле натыйжа (эски body менен 200).

экспоненциалдуу backoff + Jitler менен Retrains, катуу 'timeout/deadline'.

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

3-DS 2. x: артыкчылыктуу challenge-flow менен device-fingerprinting; журналында ECI/CAVV/DSTransID сактоо.

AVS/CVV: телеметрия жана роутинг эрежелерин текшерүү коддору кирет.

Velocity: суммасы/саны/карта/ASN/түзмөктөр боюнча чектер (1h/24h/7d).

Жүрүм-турум сигналдары: гео/убакыт зонасынын дал келбегендиги, көп карталар/аз депозиттер, тез кэшауттар.

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

Эрежелер: гео, BIN-диапазондору, карта түрү, наркы, конверсия, тобокелдик-скор.

Cascade: PSP1 → PSP2, себет жоготуу жок (idempotent token).

A/B/multi-armed bandit: айлануу жана наркы оптималдаштыруу.

Fail-open/closed: шектүү каталар үчүн safe-default (мисалы, башка соодагер аркылуу кайталоо) колдонуу, бирок, эки эсе көп үчүн эмес.

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 Webhook 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 '(idempotent) → оюнчу балансы.

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 отчетун алуу (соода/дата/валюта боюнча).

платформа реестри менен салыштыруу: 'intents/captures/refunds/payouts' 'wallet entries'.

Категориялаштыруу:

match: баары жакшы, timing: отчеттордун ортосунда кечигүү, missing_psp: платформада бар, PSP жок, missing_platform: PSP бар, платформада жок, amount_mismatch: сумманын/валютанын/fee айырмачылыгы.
Автоматтык эрежелер үчүн убакыт, билеттер/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 күн; aging берилбеген

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/аймак.

PCI DSS: PAN tokenization, эч качан CVV сактоо, зоналарды сегменттөө.

WORM-аудит: крит-операциялар (manual refund/void, merchant өзгөртүү).

RG/AML: capture/payout алдында бут; санк-барактар/РЕР; SAR/STR отчеттуулук.

PII резиденттүүлүк: аймактагы логи/отчеттор; RLS/BI маскасын.

12) Байкоо жана журнал

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

HTTP/gRPC/DB/кезек OpenTelemetry; 100% каталар/акча аномалиялар үчүн sampling.

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

13) Хаос жана DR-практикасы

PSP кулашы: Auto Cascade/" пауза new captures ".

Webhook кечигүү: дедуп + pull-API аркылуу кайра текшерүү.

Out-of-order: платформада демпотенттик жана статустук машина.

Аймактык outage: актив-пассив/актив-актив, RPO ≤ 5 мин, RTO ≤ 30 мин.

14) Чек-баракчалар

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

Бардык write жолдору менен 'X-Idempotency-Key', 'X-Trace-Id'.
Телеметрия жана лимиттер менен PSP роутинг/каскаддар.
3-DS/AVS/velocity киргизилген; тобокелдик эрежелери жана тыюу салуулар.
Webhook кол коюлган; дедуп 'event _ id'; DLQ.
Сагалар deposit/refund/payout; "кол менен оңдоолорсуз" компенсация.
Күнүмдүк текшерүү T + 1, терезелер mismatch, алерта.
PCI зонасы, PAN tokenization; WORM-аудит крит-операциялар.
RG/AML бут чейин capture/payout.

PSP-Integration/Backend касса

Ката келишимдери нормалдаштырылган; decline коддору.
кайталоо коопсуз; документтештирилген.
Тайм-ауттар/ретраи/джиттер, circuit breaker, rate limits.
Репорттор API/SFTP боюнча жеткиликтүү, бүтүндүгү кепилденген.

15) Анти-үлгүлөрү (кызыл желектер)

балансы капчыкка так командасы жок PSP Webhook боюнча өзгөрөт.

Жок демпотенттик → кош эсептен чыгаруу/кредиттер.

iFrame оюн провайдери ичиндеги орнотулган касса (RG/AML/телеметрия контролун жоготуу).

бир нече бренддер/региондордо жалпы соода ачкычтары.

Жок T + 1 текшерүү, кол Excel салыштыруу.

BI/жөнгө салуучу отчеттор түздөн-түз OLTP касса менен.

Каталар 3-DS/AVS/талдоого алынбайт.

Webhuke жок кол коюу/терезе ырастоо → реплика.

БДдагы төлөмдөрдүн/баланстардын статусун кол менен оңдоо.

16) Жыйынтык

Төлөм шлюздары менен ишенимдүү интеграция - бул "API кириши" эмес, оркестр. Ийгилик камсыз кылат:

1. Демпотенттик акча буйруктары жана дастан (authorize/capture/refund/payout).

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

3. Күнүмдүк салыштыруу (reconciliation) жана айырмачылыктарды катуу эсепке алуу.

4. Коопсуздук жана комплаенс (mTLS, кол тамгалар, PCI, RG/AML, WORM).

Бул негиздерди куруу менен платформа депозиттердин конверсиясын жогорулатат, дубль жана чарджбек тобокелдиктерин азайтат жана ишенимдүү аудиттен өтөт - ал тургай трафиктин туу чокусунда жана тышкы провайдерлердин мүчүлүштүктөрүндө.