Seamless wallet integration for casino platforms

In a seamless wallet model the player's money stays on the casino side. WGC does not store player wallets: when a game needs a balance or must record a bet, WGC sends a signed request to your platform and uses your answer. This page explains the contract in practical terms for the team that builds the handler.

How the model works

Players and balances live on your platform. WGC makes POST requests to the Callback URL you register, with three commands: getBalance to read the balance, writeBet to record a bet and its win, and rollback to cancel a bet. The only exception is a demo client created by WGC staff, which uses a test wallet of WGC.

writeBet carries a bet and its win in one call. When a studio reports the bet and the result separately, WGC joins them into one round with a round id and both calls travel inside it. The kind of operation is play, refund or, when jackpots are enabled, jackpot, and a round-finished flag marks the end of the round.

Idempotency is part of the contract

Your handler must record writeBet once per transactionId. A repeated call must not debit the player twice and must return the same balance. This is a condition of the integration, not an optional extra, because network failures make repeats normal.

Signatures

Every call is signed with HMAC-SHA256 and your account secret. Two headers are available: a signature over the body, and a second signature over the timestamp joined to the body, together with the timestamp. A new integration should verify the second one. Check the signature on the raw body before parsing the JSON, compare in constant time and reject calls older than five minutes. The documentation includes signature examples with a test secret. See also security.

Timeouts, retries and rollback

WGC waits three seconds for your answer. An answer counts only with a 2xx status. A refusal is expressed in the body, for example with an insufficient funds error and status 200, and redirects are not followed. If there is no answer in time, the bet is refused to the studio, the operation becomes unknown and a rollback follows.

A rollback asks you to cancel a whole bet: return the stake and take back the win. WGC repeats it after about a minute, then after 5, 15, 60, 360 and 1,440 minutes, and then daily for up to 30 days from the bet. Your platform keeps records of operations for at least 30 days. Support for the rollback command is optional for you; a not-found or not-allowed answer to it is not an error.

Other limits are worth knowing. A bet that waited inside WGC for more than a second and a half is not sent to you, and nothing is debited from the player. A single operation can be at most one million USD at the round's rate.

Callback address

Use a public https:// address, ideally. Private and loopback addresses are rejected when you save, only ports 443 and 80 are used and your answer should not exceed 64 KB. The addresses of WGC's own calls are shared with you in advance, and you are warned before they change.

Check your handler

Examples and a self-check are public and need no sign-in: handlers for Node.js, PHP and Python, a check script and a go-live checklist of 14 points. In the backoffice, the integration test runs 14 checks of your wallet and tells you what to fix, and the integration check shows a live log of every call with request and answer.

The test mode includes a "lose the answer" option, which checks your rollback: the operation becomes unknown and, after a minute, a rollback arrives. Read more in demo and test mode and in the integration steps.

After the round

Your platform can ask for an operation, a round or a session by its own numbers. An operation has the status accepted, refused, failed or unknown. WGC keeps the status, the response time and the first 1,024 characters of your answer for reports. Explore the Casino API, the game aggregator overview and the article on seamless wallet.

FAQ

Does WGC hold player balances?

No. Balances stay with your platform; WGC calls your Callback URL.

What happens if my server is slow?

After three seconds the bet is refused to the studio and later cancelled with a rollback.

Is the rollback command mandatory?

No, it is optional for your handler.

How do I test the handler?

Use the public examples, the self-check script and the test mode.

Ready to connect your wallet? Let's talk about your integration.

Your next connection
starts here.

Tell us what you’re building. We’ll take it from there.

Let’s connect