Session Flow

Overview

A game session represents a single play session for one player in one game. Sessions are created via the Gateway API and govern the entire lifecycle of game interactions.

Full Integration Flow

sequenceDiagram
    participant Operator
    participant Beexar
    participant Game as Game Frontend
    participant Wallet as Operator Wallet

    Note over Operator,Wallet: 1. Session Creation
    Operator->>Beexar: POST /api/v1/softswiss/launcher/real
    Beexar->>Beexar: Validate signature (HMAC-SHA256)
    Beexar->>Beexar: Create session (30 min TTL)
    Beexar-->>Operator: { launch_url }

    Note over Operator,Wallet: 2. Game Load
    Operator->>Game: Embed launch_url in iframe
    Game->>Beexar: Load with session token
    Beexar->>Wallet: POST /balance
    Wallet-->>Beexar: { balance: "500.00" }
    Beexar-->>Game: Show game UI with balance

    Note over Operator,Wallet: 3. Gameplay
    Game->>Beexar: Player places bet
    Beexar->>Wallet: POST /betwin (bet + win, finished=true)
    Wallet-->>Beexar: { balance: "509.80", transactions }
    Beexar-->>Game: Show result

    Note over Operator,Wallet: 4. Round with Rollback
    Game->>Beexar: Player places bet
    Beexar->>Wallet: POST /betwin (bet)
    Wallet-->>Beexar: 200 OK
    Note right of Beexar: Game engine error
    Beexar->>Wallet: POST /rollback (original bet)
    Wallet-->>Beexar: { balance: "509.80" }

Session Token

The session token is a 64-character hexadecimal string that uniquely identifies the session.

Property	Value
Format	64 hex characters (`[a-fA-F0-9]{64}`)
Created by	Beexar Gateway
Used by	Game frontend (passed as URL query parameter)
Lifetime	30 minutes (sliding window)

The token is embedded in the launch_url:

https://games.beexar.com/dice/casinoxyz/dice-game?token=a1b2c3d4e5f6...

Demo tokens are prefixed with demo_:

https://games.beexar.com/dice/casinoxyz/dice-game/demo?token=demo_a1b2c3d4e5f6...

Session States

flowchart LR
    Start(("●")) -- "POST /api/v1/softswiss/launcher/*" --> Created
    Created -- "Game loaded" --> Active
    Active -- "Player activity" --> Active
    Active -- "TTL expired" --> Expired
    Active -- "Player exits" --> Closed
    Expired --> End_(("●"))
    Closed --> End_

State	Description
Created	Session token generated, awaiting game load
Active	Game is loaded and the player is playing
Expired	Session TTL reached without activity
Closed	Player closed the game or navigated away

Sliding Session TTL

Sessions use a sliding window mechanism:

Property	Value
Initial TTL	30 minutes
Extension trigger	Player activity (any game action)
Extension threshold	When remaining TTL < 10 minutes
Extension amount	Reset to 30 minutes

flowchart LR
    Action["Player Action"] --> Check{"TTL < 10 min?"}
    Check -- Yes --> Extend["Extend to 30 min"]
    Check -- No --> NoOp["No change"]
    Extend --> Active["Session Active"]
    NoOp --> Active

This means an active player’s session never expires during gameplay. The session only expires after 30 minutes of inactivity.

Real-Money vs Demo Sessions

Property	Real-Money	Demo
Endpoint	`POST /api/v1/softswiss/launcher/real`	`POST /api/v1/softswiss/launcher/demo`
Token prefix	(none)	`demo_`
Wallet callbacks	Yes (`/balance`, `/betwin`, `/rollback`, `/finish`)	No
Balance source	Operator wallet	Beexar virtual wallet
TTL	30 min sliding	30 min sliding
Analytics	Recorded	Not recorded

Session Expiry

When a session expires:

Any pending bets are rolled back via /rollback
Open rounds are closed via /finish
The player is redirected to return_url if configured

Reconnection

If a player disconnects and reconnects (e.g., refreshes the page):

The game frontend loads with the same session token from the URL
If an in-progress round exists (slots free spins/bonus), the game resumes
No duplicate transactions — idempotency via id_provider