Skip to content
The Aggregator

How a game round works

Every game round flows through three actors: your operator backend, The Aggregator, and the game provider. The player sees only the game iframe; you orchestrate the wallet.

The lifecycle

Section titled “The lifecycle”

This is a representative paid-round sequence. Free-round paths may omit the bet or deliver a zero-win settlement.

sequenceDiagram
    participant Player
    participant Operator
    participant Aggregator
    participant Provider


    Player->>Operator: Opens game lobby
    Operator->>Aggregator: POST /v1/sessions (Idempotency-Key, game_id, player_id, balance, currency, country)
    Aggregator->>Provider: Create session
    Provider-->>Aggregator: Session URL
    Aggregator-->>Operator: { session_id, game_url }
    Operator->>Player: Redirect to game_url
    Player->>Provider: Plays the game
    Provider->>Aggregator: Bet callback (HMAC-signed)
    Aggregator->>Operator: POST /your-callback (bet)
    Operator-->>Aggregator: 200 OK (debited wallet)
    Provider->>Aggregator: Win callback (HMAC-signed)
    Aggregator->>Operator: POST /your-callback (win)
    Operator-->>Aggregator: 200 OK (credited wallet)
    Player->>Operator: Closes game

Step-by-step

Section titled “Step-by-step”

  1. Player opens your lobby. Your front-end calls your backend with the game they want to play.

  2. You create a session. POST /v1/sessions with an Idempotency-Key header and game_id, player_id, balance, currency, and country. The Aggregator returns session_id and game_url.

  3. You redirect the player. The game_url is a single-use signed URL. Embed it in an iframe or redirect the browser once — don’t cache or reload it. If you rely on TRUE LABS’ current URL-navigation fallback inside a sandboxed iframe, include allow-top-navigation-by-user-activation. This permission allows a player click to navigate the top-level page, so the casino page and game iframe may reload. An in-place cashier requires a separately supported same-document host hook, such as a same-route fragment handled by your front-end, or an event bridge. Do not use the broader allow-top-navigation permission.

  4. Provider sends bet callback. In this paid-round example, verify the signed bet callback, atomically commit the debit and its replayable response, then return 200. A free bet with is_free: true must not debit real money.

  5. Provider sends win callback. When the spin resolves with a payout, you receive a win callback. Credit the player’s wallet, return 200. Some zero-win legs settle internally and appear in the transactions API without an outbound callback; supported free-round paths may instead deliver a zero-amount win. Reconcile using the provider contract and free-round rules, rather than assuming one callback per API row.

  6. Player exits. The session stays open for replays. No explicit close call needed — sessions expire automatically.

Important constraints

Section titled “Important constraints”
  • game_url is single-use. Create the session immediately before redirecting the player; open it once and don’t cache, reload, or pre-fetch it.
  • Callbacks may arrive out-of-order under network jitter. The Aggregator does best-effort ordering but cannot guarantee strict sequence. Deduplicate by integration/organization, provider_code and transaction_id and replay the stored original status and body.
  • A session can have many bets and wins. Slot games typically generate one bet and one win per spin; live casino games can interleave them differently.
  • Retry eligibility depends on the delivery path and deployed policy. A non-2xx response does not guarantee queuing or manual replay. See Wallet callbacks for retry semantics.
Section titled “Read next”