Интеграция с платёжными шлюзами: флоу, возвраты, 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`).

Повтор с тем же ключом → тот же результат (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 несверенных < N.

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; санк-листы/PEP; 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).

Построив эти основы, платформа повышает конверсию депозитов, снижает риски дублей и чарджбеков и уверенно проходит аудит — даже в пике трафика и при сбоях внешних провайдеров.