Why the same call arrives twice

Take the common case. WGC calls your Callback URL with a bet, you debit the player and answer, and your answer is lost on the way. From WGC's side the operation is unknown: it does not know whether you booked it. A game provider may also retry a bet after a failure on its own side. In both cases the repeat carries the same transactionId. A handler that treats it as a new bet debits the player twice, and the dispute that follows is expensive for everyone.

For this reason idempotency in the WGC wallet is a condition of the integration, not a wish: writeBet is recorded once per transactionId, and a repeat does not debit twice and returns the same balance.

Who repeats what

The two commands repeat in different ways, and it helps to keep them apart.

  • writeBet is repeated by the game provider, not by WGC, and the repeat comes with the same transactionId. WGC answers a repeat of an operation it has already settled from what it stored. Only when the earlier attempt never reached you does the call go out again, with the same transactionId.
  • rollback is repeated by WGC, on a fixed schedule that is not a setting: about a minute after the missing answer, then after 5, 15, 60, 360 and 1,440 minutes, then once a day until 30 days have passed since the bet. After that the retries stop and WGC staff settle the case with you.

Keep your own record of every transaction, by transactionId, for at least 30 days, because a rollback can come up to 30 days after the bet.

The rules for a safe `writeBet`

  1. Make transactionId unique in your database. The easy way to be idempotent is a unique key: the second insert fails, and you answer with what you stored for the first.
  2. Answer a repeat exactly as you answered the first time. The same balance, no second debit. A repeat of a refusal is the same refusal.
  3. Handle two identical calls at the same moment. A check-then-write on separate steps can let both through. The unique key, or a lock, decides who is first.
  4. Refuse a kind you do not know. kind is play or refund, and jackpot only after your manager switches jackpots on for your account.
  5. Ignore fields you do not know. New fields can appear.

A repeat is shown below. Both calls carry the same transactionId, and both get the same answer.

{ "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 }

The rules for a safe `rollback`

A rollback asks you to reverse a bet entirely: the bet goes back to the player, and the win is taken back. It is idempotent too: the same transactionId again must not reverse twice.

{ "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
  • If you never booked that transactionId, change nothing and still answer with the balance.
  • WGC counts a rollback as taken only with an HTTP 2xx and a readable balance. A refusal, a timeout or an unreadable answer is a refusal, and the schedule goes on, so a repeated rollback must also be answered with a 2xx.
  • A 404, a 405 or unknown_command tells WGC that you do not implement rollbacks. WGC then stops repeating, and the case is settled with you by staff.
  • A writeBet that arrives after its own rollback should be refused, as the public example handlers do.

Timeouts and what counts as an answer

WGC waits 3 seconds for your answer, and an answer is taken as given only with a status from 200 to 299. A 500 with {"ok":true} in the body does not count: the operation becomes unknown, and a rollback follows. A refusal is a normal answer: { "ok": false, "error": "insufficient_funds" } with status 200. Redirects are not followed.

Two shorter deadlines protect the player. A stake that waited more than 1.5 seconds inside WGC is not sent to you, and nothing is taken. A stake you accepted whose answer could not reach the game provider within 4.5 seconds is cancelled at once through a rollback. Wins, jackpots and refunds have no such deadline: they always reach you.

Each call is signed. Check the signature on the raw body before you parse it, compare in constant time, and reject a call whose timestamp is older than 5 minutes.

Opening a session is a different contract

Do not carry the wallet rules over to POST /v1/sessions. There, the optional Idempotency-Key header lives 24 hours: the same key and the same body return the same answer without a new call to the game provider, and the same key with another body is invalid_request. While a session is open, a second open for the same player, game, currency and mode returns that session and the same launch link. Test both contracts as separate cases.

Prove it before real play

  • Public examples and a self-check. Node.js, PHP and Python handlers and the wallet-check.mjs script are public. The self-check sends two identical writeBet calls at once and expects one debit and the same answer to both.
  • The integration test. In the back office it runs 14 checks of your wallet. Three of them are about repeats: the same transactionId again is not charged twice, two equal bets at the same moment charge once, and a repeated rollback returns nothing more and is taken.
  • The test game. A test key opens WGC Test Slot, where each spin makes two real calls to your Callback URL with "test": true, without money. An option to lose the answer makes the operation unknown, and about a minute later a rollback arrives.
  • Integration check. It shows every call and answer live. After a run, the status of an operation and of its rollback can be read with GET /v1/transactions/{transactionId}.

See demo and test mode, the integration steps and the Casino API overview; the contract is on the seamless wallet page.