The session request

Your server opens a game for a player with POST /v1/sessions. The call is server to server: the key goes in the X-API-Key header, and the browser never calls the API.

POST /v1/sessions
{"publicId":"sweet-bonanza-1","playerId":"casino-side-player-42","currency":"USD","mode":"demo","language":"en"}
→ 200 { "ok": true, "requestId": "req_…", "data": { "url": "https://play.worldgamingconnect.com/play/Zk3p9xQ2vL8mTn4r", "sessionId": "cmgq3r8v40001l8xyz5k2abcd", "expiresAt": "2026-10-12T10:45:00.000Z" } }

The required fields are playerId, currency, mode and exactly one of publicId or universalId. The player id is 1 to 64 printable ASCII characters and names a player in your own system: WGC creates no player, because the wallet stays in your casino. The currency is a code of 3 to 8 letters, and the mode is real or demo. Optional fields set the language, the return address, the platform (desktop or mobile), the player's country, your own session number and, for games that accept them, the RTP and the bet limits.

What the answer holds

url is the launch link, sessionId is the number of the session as your casino will see it, and expiresAt is the time until which an unopened link works. Keep the session id: it is the number you use later to look up the session, and the number in the reports.

Open the link in the player's browser

The link is WGC's own address, and it must be opened in the player's browser, by redirecting the page to it or by putting it in a frame. Do not fetch it from your server. The link records the device that opens it, and a fetch from your server would be recorded as the player's open.

How long the link lives

  • A link that no browser has opened works for 5 minutes. To open it later, ask for a new one with a new session request.
  • Once the player's browser has opened it, the link lives as long as the player keeps playing, that is, while wallet calls keep coming.
  • After the session is closed, the link answers with a clear page and status 410. To play again, the game is opened again from your lobby with a new session request.

Put the link in a frame

The link can be placed in an <iframe> with allow="fullscreen; autoplay". Do not add a sandbox attribute unless it carries at least allow-scripts allow-same-origin allow-popups, because a stricter sandbox stops the game from running. For some games the link works once: a refresh in a new tab is a second open of it. When that happens, call the session request again and open the new link, which is the same session with a fresh game address.

The return address and the language

returnUrl brings the player back to your lobby when the game ends. Without it, WGC shows a neutral page. Not every game accepts a return address, and the in-game lobby does not work for every studio, so give players a way out of the frame on your own page.

The language is an ISO 639-1 code. A region such as pt-BR is allowed and the region is cut. A country code sent instead of a language is replaced, so ua becomes uk. An unknown code falls back to English, and the game is never refused because of the language. What the game really shows is up to the studio.

One open session per player and game

While a session is open, a second request for the same player, game, currency and mode returns that session and the same launch link. Two opens at the same moment, such as a double click, both answer with the same session, and if the first has no link yet the other answers try_later. A different player, currency or mode is a different session. After the session is closed, the next open creates a new one.

The optional Idempotency-Key header, valid for 24 hours, makes a repeated request safe: the same key and the same body return the same answer without a new call to the studio, and a different body is invalid_request. A key does not renew an expired link: after expiresAt, open the session with a new key.

Refusals to expect

error.codeHTTPWhat to do
unauthorized401Check the key.
invalid_request400Fix the field named in the message. A demo open with a production key is refused too.
not_found404The game is missing, not issued to your account or not priced for it. Do not probe.
currency_not_granted400The currency is not issued to your account.
balance_required402A real session needs money on the account. Top up, or open a demo with a test key.
country_restricted403The studio forbids the game in the player's country. Offer another game.
rate_limited429Wait the number of seconds in Retry-After.
try_later409The previous open with this key is still running. Retry in a second.
busy503WGC is under load; retry after Retry-After.

Branch only on error.code; the message is for people. A game that is unavailable in some currency is marked in the catalog, and a launch in that currency is refused while other currencies keep working. A real launch needs funds on your commercial account: the balance plus the credit limit must be above zero, while a demo launch moves no money. Opening sessions is limited per key, and the default is 600 a minute.

Reading a session later

Your server can read a session by its number with GET /v1/sessions/{sessionId}, which shows its status, the currency, the mode and the totals, or find your sessions by your own number with GET /v1/sessions?casinoSessionId=. Only your account's sessions are visible. In support requests, quote the session id, the request id and the time in UTC. For what happens inside a round, see the round flow, and for repeats, the idempotency article.

See the Casino API overview, the integration steps, demo and test mode and the seamless wallet page for the calls that follow the launch.