Create a real-money session
POST/sessions
Create a real-money game session. The player is redirected to the
returned game_url to begin playing. The URL is single-use — open it
once and do not cache or reload it; create the session immediately
before redirecting.
Requires Idempotency-Key header. Retries with the same key within
24 hours return the cached response.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Persist one key per logical operation and reuse it only with the unchanged request body. Replay behavior and retention depend on the endpoint; see https://docs.aggregator.gg/guides/idempotency/.
Request Bodyrequired
Section titled “Request Bodyrequired”object
The Aggregator catalog game UUID — the id field returned by
GET /v1/games. This is NOT the provider’s own game code
(provider_game_id); always pass The Aggregator id.
Operator’s internal player identifier.
Player’s current real-money balance in minor units (e.g. cents for USD/EUR/GBP). The Aggregator does not hold balances — this is informational only, used for limit checks and game UX.
ISO 3166-1 alpha-2 country code of the player.
enHTTPS URL to redirect the player after the session ends. When omitted, the Aggregator’s game-complete page is used.
Optional HTTPS cashier destination for providers that support a separate in-game deposit or Top-up URL, including TRUE LABS and Apparat. Other providers may ignore it. If omitted, it falls back to the effective return_url, including the Aggregator game-complete fallback. This URL does not invoke a cashier modal by itself. For a same-document fragment hook, match the current top-level origin, path and query exactly and handle the fragment in the host page. Other destinations may reload the casino page and game iframe.
https://casino.example/game/abc#depositPlatform accounts only. Selects which brand (sub-operator) under
your platform this launch belongs to. Omitting it bills and reports
the launch under your platform’s default brand rather than
failing — so a code path that forgets the parameter still launches,
but its spins are attributed to default instead of the real brand.
Wire it everywhere you launch. Sending it from a non-platform key is
a 400 (E6006); with no default brand provisioned the call is a 409
(E6010), and a platform configured with require_sub_operator_ref
gets a 400 (E6005) instead of the default — opt into that if a
missing parameter should be loud.
The first request bearing an unseen ref — a launch, or a
GET /v1/games — creates the brand with the same games and providers your
platform already has available; afterwards the
same ref always resolves to the same brand. Matched
case-insensitively — Brand-01 and brand-01 are one brand, not
two.
Format: 1-32 characters of [A-Za-z0-9_-], starting and ending
alphanumeric. : is not allowed. A ref that does not match is a 400
(E6004) — refs are validated, never silently repaired, because a
repaired typo would mint a phantom brand and split its money.
Omit it, never send it empty. An absent field resolves to the
default brand; "" (or whitespace) is a 400 (E6004). The two are
different on purpose: a field you never sent cannot have been meant
to name a brand, whereas a field you sent blank means your caller
has the parameter and the value behind it came out empty — that
request believes it selected a brand, and answering it with the
default one would bill a different brand’s ledger and return 201 as
if nothing were wrong.
Responses
Section titled “Responses”Session created.
object
One-time-use signed URL the player is redirected to.
Reserved for legacy use. Currently never set.
Headers
Section titled “Headers”Present when the response was served from the idempotency cache.
Validation failed or missing/invalid Idempotency-Key header.
object
object
Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction,
player_self_excluded). Branch on code; type is for readability.
game_blocked_jurisdictionCorrelation ID for support escalation.
object
Missing, invalid, or revoked API key.
object
object
Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction,
player_self_excluded). Branch on code; type is for readability.
game_blocked_jurisdictionCorrelation ID for support escalation.
object
Game or player not eligible. The error.code distinguishes:
E2002 game not enabled for the operator, E2003 game blocked in the
player’s country (jurisdiction), E3004 player self-excluded, or
operator_settings_not_configured when the operator has no wallet
callback configured for the provider.
object
object
Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction,
player_self_excluded). Branch on code; type is for readability.
game_blocked_jurisdictionCorrelation ID for support escalation.
object
Game not found (error.code = E2001).
object
object
Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction,
player_self_excluded). Branch on code; type is for readability.
game_blocked_jurisdictionCorrelation ID for support escalation.
object
Idempotency key reused with a different request body.
object
object
Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction,
player_self_excluded). Branch on code; type is for readability.
game_blocked_jurisdictionCorrelation ID for support escalation.
object
Rate limit exceeded; consult Retry-After.
object
object
Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction,
player_self_excluded). Branch on code; type is for readability.
game_blocked_jurisdictionCorrelation ID for support escalation.
object
Headers
Section titled “Headers”Seconds to wait before retry.
Provider returned an error when creating the session.
object
object
Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction,
player_self_excluded). Branch on code; type is for readability.
game_blocked_jurisdictionCorrelation ID for support escalation.
object
Provider temporarily unavailable.
object
object
Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction,
player_self_excluded). Branch on code; type is for readability.
game_blocked_jurisdictionCorrelation ID for support escalation.