Інтеграція з платіжними шлюзами: флоу, повернення, 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/ліміти .

Підтвердження «чотирьох очей» для 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').

Повтор з тим же ключем → той же результат (200 зі старим body).

Ретраї з експоненціальним backoff + джиттер, жорсткі'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-діапазони, тип карти, вартість, конверсія, ризик-скор.

Каскад: 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'по каналу/гео, aging невірених транзакцій> N днів.

9) Chargeback / Dispute

Життєвий цикл: notification → evidence → representment → arbitration.

Зберігайте evidence-пакети (KYC, IP/ASN, device, 3-DS результати, usage-логи).

Тісний зв'язок з risk/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/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 включені; risk-правила і бани.
Вебхуки підписані; дедуп по'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. Роутинг і каскади PSP з 3-DS/AVS/velocity і реальною телеметрією.

3. Щоденна звірка (reconciliation) і строгий облік розбіжностей.

4. Безпека та комплаєнс (mTLS, підписи, PCI, RG/AML, WORM).

Побудувавши ці основи, платформа підвищує конверсію депозитів, знижує ризики дублів і чарджбеків і впевнено проходить аудит - навіть в піку трафіку і при збоях зовнішніх провайдерів.