Почему один и тот же вызов приходит дважды

Возьмём обычный случай. 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`

  1. Сделайте transactionId уникальным в своей базе. Простой способ быть идемпотентным — уникальный ключ: вторая вставка не проходит, и вы отвечаете тем, что сохранили для первой.
  2. Отвечайте на повтор ровно так, как ответили в первый раз. Тот же баланс, без второго списания. Повтор отказа — тот же отказ.
  3. Обработайте два одинаковых вызова в один момент. Схема «проверить, потом записать» в отдельных шагах может пропустить оба. Кто первый, решает уникальный ключ или блокировка.
  4. Отклоняйте kind, который не знаете. kind — play или refund, а jackpot — только после того, как ваш менеджер включил джекпоты для вашего аккаунта.
  5. Игнорируйте поля, которых не знаете. Новые поля могут появиться.

Повтор показан ниже. Оба вызова несут один и тот же 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-кошелька.