Единый кошелёк или трансферный кошелёк

Коротко

Единый кошелёк (seamless)

В модели единого кошелька (seamless) кошельком является ваша система. Когда игрок делает ставку, SSG API вызывает ваш callback-эндпоинт, вы меняете баланс в своём реестре и отвечаете новым балансом. Средства никогда не покидают вашу базу данных.

Последовательность обращений

1. Запуск: ваш бэкенд запрашивает у SSG URL игры с ID игрока и токеном сессии.
2. Ставка: для каждого раунда SSG вызывает debit с уникальным txId. Вы проверяете средства, пишете строку реестра и возвращаете новый баланс.
3. Выигрыш: SSG вызывает credit с выплатой (она может быть нулевой) для того же раунда.
4. Сбой: если обращение превышает таймаут, SSG повторяет его с тем же txId, а после лимита повторов отправляет rollback.

Методы callback (иллюстрация)

{
  "method": "debit",
  "playerId": "p_839201",
  "txId": "tx_20261007_000184",
  "roundId": "r_77f3a1",
  "gameId": "slots_fruit_01",
  "currency": "MYR",
  "amount": "2.50",
  "ts": 1791338577,
  "sign": "hex(HMAC-SHA256(secret, canonical))"
}

{
  "status": "OK",
  "txId": "tx_20261007_000184",
  "balance": "97.50",
  "currency": "MYR"
}
// errors: INSUFFICIENT_FUNDS, PLAYER_NOT_FOUND,
//         DUPLICATE_TX (return original result), INTERNAL_ERROR

Правила, которым должен следовать ваш сервис кошелька

Идемпотентность

Повторный debit или credit с тем же txId должен вернуть исходный результат и не двигать деньги снова. Обеспечьте это уникальным индексом по txId.

Атомарная запись в реестр

Проверка баланса, вставка строки реестра и обновление баланса — в одной транзакции базы данных, чтобы две одновременные ставки не могли увести баланс в минус.

Rollback раньше debit

Rollback может прийти для txId, которого вы не видели, потому что исходный debit превысил таймаут. Сохраните метку-«надгробие», чтобы поздний debit с этим txId был отклонён.

Бюджет задержки

Цель — p99 ниже 500 мс с учётом сети. Ограничьте путь callback одним индексированным чтением и одной записью и не нагружайте его отчётными запросами.

Формат денег

Храните суммы как десятичные строки или целые минимальные единицы. Никогда не используйте числа с плавающей точкой и проверяйте валюту по аккаунту игрока.

Бонусы и фриспины

Фриспин — это debit на 0, за которым следует credit выигрыша. Держите промо-балансы отдельно от денежного баланса в реестре.

Безопасность

Проверяйте подпись HMAC-SHA256 канонического запроса, отклоняйте устаревшие метки времени, разрешайте только IP-адреса SSG и требуйте TLS 1.2 или выше.

Сверка

Сравнивайте ежедневные отчёты SSG по раундам со своим реестром по roundId. Расхождения указывают на пропущенные callback или rollback.

Трансферный кошелёк

В модели трансферного кошелька провайдер хранит игровой баланс для каждого игрока. Ваш бэкенд переводит средства туда перед игрой и обратно после. Во время игры к вашей системе нет обращений callback, поэтому нужны только исходящие REST-вызовы.

Последовательность обращений

1. Перевод внутрь: ваш бэкенд вызывает transferIn с уникальным txId и суммой. Результат — PENDING или SUCCESS.
2. Игра: запустите игру. Все ставки и выигрыши меняют баланс на стороне провайдера без обращений к вам.
3. Перевод наружу: когда игрок уходит, вызовите transferOut на весь баланс и при SUCCESS зачислите его обратно в свой реестр.
4. Неизвестный результат: если вызов перевода превысил таймаут, прежде всего запросите getTransferStatus с тем же txId.

Методы API (иллюстрация)

Правила, которым должен следовать ваш бэкенд

Один txId на одно намерение

Создавайте txId до первого вызова и используйте его при каждом повторе. Не создавайте новый txId, пока не известен статус предыдущего.

Сначала списание в вашем реестре

При переводе внутрь зарезервируйте сумму в реестре до вызова SSG, затем подтвердите или освободите её, когда статус станет окончательным.

Собирайте зависшие балансы

Запускайте задачу, которая находит игроков с игровым балансом без активной сессии и переводит его обратно. Это покрывает игроков, закрывших браузер посреди сессии.

Отыгрыш и отчёты

Поскольку вы не видите ставки в реальном времени, считайте оборот, отыгрыш бонусов и лимиты риска по отчётам о раундах из SSG, а не по callback.

Сверка

Сопоставляйте каждый перевод внутрь и наружу с записями SSG по txId и поднимайте тревогу при любом PENDING старше вашего таймаута.

Безопасность

Подписывайте запросы HMAC-SHA256, обращайтесь только по TLS 1.2 или выше, храните API-ключи в хранилище секретов и ограничьте, какие ваши серверы могут обращаться к SSG.

Сценарии сбоев

Что выбрать

Многие операторы запускаются на трансферном кошельке, а затем переходят на единый, когда их собственный сервис кошелька готов. Спросите нас, как организуется переход.

Чек-лист интеграции

• Уникальный индекс по txId и идемпотентные обработчики для каждого обращения, двигающего деньги
• Проверка подписи HMAC, допуск по метке времени и список разрешённых IP
• Безопасные десятичные суммы и проверка валюты
• Тесты таймаутов, повторов и rollback в песочнице, включая поздний повтор
• Ежедневная задача сверки по roundId (единый) или txId (трансферный)
• Мониторинг и оповещения: задержка callback, доля ошибок, незавершённые переводы, зависшие балансы