Почему один и тот же вызов приходит дважды
Возьмём обычный случай. WGC вызывает ваш Callback URL со ставкой, вы списываете деньги с игрока и отвечаете, а ваш ответ теряется по дороге. С точки зрения WGC операция неизвестна: он не знает, провели вы её или нет. Провайдер игры тоже может повторить ставку после сбоя на своей стороне. В обоих случаях повтор приходит с тем же transactionId. Обработчик, который принимает его за новую ставку, спишет деньги с игрока дважды, а последующий спор дорого обойдётся всем.
Поэтому в кошельке WGC это правило, напрямую касающееся денег игрока, — не пожелание, а условие интеграции: writeBet записывается один раз на transactionId, а повторный вызов не списывает дважды и возвращает тот же баланс.
Кто что повторяет
Две команды повторяются по-разному, и их полезно не смешивать.
writeBetповторяет провайдер игры, а не WGC, и повтор приходит с тем жеtransactionId. Повтор уже проведённой операции WGC отвечает из того, что сохранил. Только когда прошлая попытка до вас не дошла, вызов уходит снова — с тем жеtransactionId.rollbackповторяет WGC по фиксированному графику, который не настраивается: примерно через минуту после пропавшего ответа, затем через 5, 15, 60, 360 и 1 440 минут, а потом раз в сутки, пока не пройдёт 30 суток со ставки. После этого повторы прекращаются, и случай разбирает сотрудник WGC вместе с вами.
Храните собственные записи о каждой транзакции по transactionId не меньше 30 суток, потому что откат может прийти через 30 суток после ставки.
Правила безопасного `writeBet`
- Сделайте
transactionIdуникальным в своей базе. Простой способ быть идемпотентным — уникальный ключ: вторая вставка не проходит, и вы отвечаете тем, что сохранили для первой. - Отвечайте на повтор ровно так, как ответили в первый раз. Тот же баланс, без второго списания. Повтор отказа — тот же отказ.
- Обработайте два одинаковых вызова в один момент. Схема «проверить, потом записать» в отдельных шагах может пропустить оба. Кто первый, решает уникальный ключ или блокировка.
- Отклоняйте
kind, который не знаете.kind—playилиrefund, аjackpot— только после того, как ваш менеджер включил джекпоты для вашего аккаунта. - Игнорируйте поля, которых не знаете. Новые поля могут появиться.
Повтор показан ниже. Оба вызова несут один и тот же transactionId, и оба получают один и тот же ответ.
{ "command": "writeBet", "playerId": "casino-side-player-42", "currency": "USD", "bet": 1.00, "win": 0.00, "roundId": "3f1c2a64-8d0b-4e57-9b7a-5c2e1d0f9a41", "gamePublicId": "sweet-bonanza-1", "transactionId": "5f0b1c2e-7a64-4d6e-9a3b-0c1d2e3f4a5b", "kind": "play", "requestId": "req_…", "timestamp": "2026-10-12T10:15:01.000Z" }
← { "ok": true, "balance": 122.45 }
(the same call again)
← { "ok": true, "balance": 122.45 }Правила безопасного `rollback`
rollback просит отменить ставку целиком: ставка возвращается игроку, выигрыш забирается. Он тоже идемпотентен: тот же transactionId ещё раз не должен отменять дважды.
{ "command": "rollback", "transactionId": "5f0b1c2e-7a64-4d6e-9a3b-0c1d2e3f4a5b", "playerId": "casino-side-player-42", "currency": "USD", "bet": 1.00, "win": 0.00, "reason": "unknown_outcome", "requestId": "rb:5f0b1c2e-7a64-4d6e-9a3b-0c1d2e3f4a5b:1", "timestamp": "2026-10-12T10:16:01.000Z" }
← 200 { "balance": 123.45 } # taken
← 200 { "ok": false, "error": "insufficient_funds" } # a refusal: WGC asks again
← 404, 405, or { "error": "unknown_command" } # not implemented: not a failure- Если вы никогда не проводили этот
transactionId, ничего не меняйте и всё равно отвечайте балансом. - WGC считает откат принятым только при HTTP 2xx и читаемом балансе. Отказ, таймаут или нечитаемый ответ — это отказ, и график продолжается, поэтому повторный откат тоже нужно отвечать кодом 2xx.
- 404, 405 или
unknown_commandсообщают WGC, что вы не реализуете откаты. Тогда WGC перестаёт повторять, а случай разбирает сотрудник вместе с вами. writeBet, пришедший после собственного отката, следует отклонить — так делают и публичные примеры обработчиков.
Таймауты и что считается ответом
WGC ждёт ваш ответ 3 секунды, и ответ считается данным только со статусом от 200 до 299. 500 с {"ok":true} в теле не считается: операция становится неизвестной, и следует откат. Отказ — нормальный ответ: { "ok": false, "error": "insufficient_funds" } со статусом 200. Перенаправления не выполняются, поэтому отвечайте прямо с адреса Callback, без переадресации на другой.
Игрока защищают два более коротких срока. Ставка, которая ждала внутри WGC дольше 1,5 секунды, вам не отправляется, и ничего не списывается. Принятая вами ставка, ответ на которую не дошёл до провайдера игры за 4,5 секунды, сразу отменяется откатом. У выигрышей, джекпотов и возвратов такого срока нет: они всегда доходят до вас.
Каждый вызов подписан. Проверяйте подпись по необработанному телу до разбора, сравнивайте за постоянное время и отклоняйте вызов, у которого метка времени старше 5 минут.
Открытие сессии — другой контракт
Не переносите правила кошелька на POST /v1/sessions. Там необязательный заголовок Idempotency-Key живёт 24 часа: тот же ключ и то же тело возвращают тот же ответ без нового обращения к провайдеру игры, а тот же ключ с другим телом — invalid_request. Пока сессия открыта, второе открытие для того же игрока, игры, валюты и режима возвращает эту сессию и ту же ссылку запуска. Проверяйте оба контракта отдельными случаями — так легко понять, из какого из них пришла ошибка.
Докажите до реальной игры
- Публичные примеры и самопроверка. Обработчики на Node.js, PHP и Python и скрипт
wallet-check.mjsоткрыты. Самопроверка отправляет сразу два одинаковыхwriteBetи ждёт одного списания и одного и того же ответа на оба. - Тест интеграции. В бэкофисе он выполняет 14 проверок вашего кошелька. Три из них — про повторы: тот же
transactionIdещё раз не списывается дважды, две одинаковые ставки в один момент списывают один раз, а повторный откат больше ничего не возвращает и принимается. - Тестовая игра. Тестовый ключ открывает WGC Test Slot, где каждый спин делает два настоящих вызова на ваш Callback URL с
"test": true, без денег. Опция «потерять ответ» делает операцию неизвестной, и примерно через минуту приходитrollback. - Integration check. Показывает каждый вызов и ответ вживую. После прогона статус операции и её отката читается через
GET /v1/transactions/{transactionId}.
См. демо и тестовый режим, шаги интеграции и обзор Casino API; контракт — на странице seamless-кошелька.