Как устроена интеграция платёжных систем

Платежи — это «аорта» онлайн-казино. От того, как устроена интеграция с платёжными провайдерами (PSP), зависит конверсия в первый депозит, скорость вывода, доля чарджбеков, нагрузка саппорта и даже репутация у регулятора. Ниже — практическая карта: какие компоненты нужны, как течёт запрос, где ставить защиту и что считать.

1) Архитектура платёжного контура

Основные блоки:

Касса (Checkout UI): выбор метода/валюты/суммы, 3DS/SCA, статусы, ошибки.
Платёжный шлюз (Gateway): маршрутизация на PSP по правилам (страна, валюта, риск, стоимость).
Кошелёк (PAM/Wallet): учёт баланса, лимиты RG, транзакции `debit/credit`.
Антифрод/AML: скоринг операции до и после авторизации.
Вебхуки (Callbacks): подтверждают финальные статусы.
Биллинг/Свёрка (Reconciliation): ежедневное совпадение денег в PSP и в кошельке.
Хранилище токенов: карты/кошельки через токенизацию PSP, без «сырых» PAN.

Маршрутизация на несколько PSP:

Правила по странам/банкам/валютам/лимитам, A/B-линии, автоматический фэйловер при деградации.

2) Потоки «депозит» и «вывод» (схемы)

Депозит (карта/кошелёк/банкинг):

1. `POST /payments/init` → создать намерение (amount, currency, method).

2. Редирект/SDK → 3DS/SCA/биометрия.

3. PSP возвращает предварительный статус (authorized/pending/failed).

4. Webhook PSP → финальный статус (captured/failed).

5. `wallet/credit` по финалу + запись лимитов RG/истории.

Вывод:

1. `POST /payouts/init` → проверка вейджера/лимитов/риска.

2. Инициация payout в PSP (в идеале — тот же маршрут, что и депозит).

3. Webhook PSP → success/failed.

4. `wallet/debit` при success, журнал причин при отказе, уведомление игрока.

3) Идемпотентность и связность денег

Каждый вызов — с `Idempotency-Key` и уникальным `txn_id`.

Депозиты/выводы меняют баланс только один раз — по финальному webhook.

Любой повтор запроса возвращает тот же `txn_id` и статус.

В связке с играми: `round_id` ↔ `debit_txn_id`/`credit_txn_id`.

4) Безопасность и комплаенс

TLS 1.2+/1.3, HSTS; webhooks с HMAC-подписью и anti-replay (`timestamp`, nonce).

Tokenization карт у PSP; PCI DSS scope-редукция (hosted fields/pages).

SCA/3DS2 для карт, PSD2/Open Banking для Pay-by-Bank.

GDPR: минимизация PII, ретенция, DSR-процессы; журнал доступа к профилям.

mTLS/IP allow-list для соединений с PSP, сегрегация платёжного контура.

5) Антифрод и AML (до и после платежа)

Pre-auth правила: гео/ASN, устройство, velocity, поведение, «pass-through».

ML-скоринг/граф: общие карты/кошельки/устройства, повторные chargeback.

Post-auth мониторинг: отмены, возвраты, быстрый вывод.

AML-сценарии: пороги, structuring, необычные маршруты, отчёты STR/SAR.

Step-up KYC: при средне/высоком риске перед выводом.

6) Вебхуки: надёжная доставка

Подпись HMAC, проверка `timestamp` и дедупликация по `event_id`.

Ретраи на стороне PSP — идемпотентные.

Логи доставки (success/fail), dead-letter queue и ручной «replay».

Webhook не меняет баланс, если не совпадает сумма/идентификаторы.

7) Ошибки и таймауты: дизайн ответов

Коды: `402` (payment required), `409` (идемпотентный конфликт), `422` (валидация), `429` (rate-limit), `5xx` (инцидент).

Тела ошибок: `error`, `message`, `trace_id`, `details{…}` — помогают саппорту и алёртам.

Graceful retry на клиенте (экспоненциальный бэкофф), чёткие подсказки в UI.

8) Роутинг и фэйловер на несколько PSP

Правила качества: p95 авторизаций, конверсия, доля 3DS-фейлов, стоимость.

Смарт-роутер: при ухудшении метрик — перевод трафика на альтернативу.

Sticky-маршрут на сессию/банк для стабильности 3DS.

План деградации: выключение «тяжёлых» методов, оставляя быстрые (P2P/Pay-by-Bank), очередь выводов.

9) Свёрка и финансы (Reconciliation)

Ежедневная выгрузка PSP и автосверка с кошельком: совпадение сумм, комиссий, возвратов.

Несовпадения → кейсы на расследование.

Отдельные отчёты по chargeback/refund/fees, расчёт истинной маржи по методам.

10) Метрики, которые надо держать в фокусе

Конверсия депозита по методу/банку/стране/устройству.

Время депозита/вывода (p50/p95).

Доля 3DS-фейлов, отмен, возвратов, chargeback rate.

Доля ручных ревью и TTV KYC.

Uptime PSP и собственный error-rate по маршрутам.

Cost per success и ROI по методам.

11) Пример минимального API (сокращённо)

Создать намерение депозита

`POST /v1/payments/init`

json
{
"amount":"50.00",  "currency":"EUR",  "method":"card",  "return_url":"https://app.example.com/checkout/return",  "idempotency_key":"b6a1-…",  "meta":{"country":"FI","device":"ios"}
}

Ответ

json
{"payment_id":"pay_123","status":"pending","redirect_url":"https://psp.example/3ds/…"}

Webhook статуса

`POST /v1/payments/webhook` + `X-Signature: sha256=…`

json
{
"event_id":"evt_789",  "payment_id":"pay_123",  "status":"captured",  "amount":"50.00",  "currency":"EUR",  "timestamp":"2025-10-17T09:41:00Z"
}

Провести зачисление (внутри платформы)

`POST /v1/wallet/credit`

json
{"payment_id":"pay_123","txn_id":"txn_555","amount":"50.00","idempotency_key":"b6a1-…"}

12) Доступность и UX кассы

Минимум шагов: auto-detect страны/валюты, сохранённые токены методов.

Локальные методы: банковские кнопки, e-wallets, Apple/Google Pay.

Прозрачность: комиссии/ETA вывода, статус операции, понятные ошибки.

Доступность: крупные элементы, контраст, screen readers, многоязычие.

13) DR/BCP и безопасность операций

Репликация платёжных журналов, бэкапы с шифрованием, ежеквартальные DR-учения.

RPO/RTO задокументированы, флоу «отложенных» выплат при сбое PSP.

WAF/бот-менеджмент на кассе, но исключения для редиректов/SDK PSP.

14) Частые ошибки

Баланс меняется до финала webhook → дубли/рассинхрон.

Нет `Idempotency-Key` → повтор при сетевых сбоях создаёт вторую операцию.

Слабая проверка подписи webhook → подмена статусов.

Отсутствие автосверки с PSP → «тихие расхождения».

Один PSP «на всё» → простои и потери конверсии при деградации.

Валидация 3DS/адресных полей «для галочки» → рост чарджбеков.

15) Чеклист внедрения (сохраните)

Мульти-PSP роутер, правила качества, фэйловер
Idempotency на каждом слое (`txn_id`, `Idempotency-Key`)
Webhooks: HMAC, anti-replay, логи доставки, дедупликация
Tokenization/hosted fields, PCI DSS scope-редукция
3DS2/SCA, PSD2/Open Banking где доступно
Антифрод/AML до и после платежа, step-up KYC
Автосверка отчётов PSP, разбор несоответствий
Наблюдаемость: p95 депозита/вывода, 3DS fail-rate, uptime PSP
DR-план, отложенные выплаты, бэкапы журналов
UX кассы: локальные методы, прозрачные ETA/комиссии, доступность

Хорошая платёжная интеграция — это не «подключить SDK», а выстроить устойчивый контур: мульти-PSP маршрутизация, строгая идемпотентность, подписанные webhooks, антифрод/AML, автосверка и наблюдаемость. Такой стек повышает конверсию, ускоряет вывод, снижает риски чарджбеков и делает платформу предсказуемой для игроков, партнёров и регуляторов.