Skip to content
LootBox Solutions

Concepts & glossary

Definitions used throughout. Skim once; refer back as needed.

Core entities

  • Operator / brand — your integration. Reachable at https://{operator}.app.lootboxsolutions.com. Holds your API keys, wallet/webhook URLs, enabled games, branding, currencies, and locales.
  • Player external id (playerExternalId) — the stable opaque id you assign each player. The only player identity LootBox Solutions stores. No PII.
  • Box — a mystery box: a product a player can open for a chance at prizes.
  • Box version — an immutable snapshot of a box’s price, odds, and prize table. A box always has a current version; opening references a specific boxVersionId, so pricing/odds can’t shift mid-flight.
  • Prize / inventory item — what a player wins. Lands in their inventory and can be cashed back or shipped. See Inventory & fulfillment.
  • Game key — which game a session plays. Today: mystery_box.
  • Game app — the player-facing app LootBox Solutions serves and you embed as an iframe (at /play). It renders the box catalog, runs the open/draw animation, shows balances, and talks to the Player API with the session token. Themed per operator via branding settings. (In the embedding model it’s the in-iframe surface; you can also build your own client against the same Player API.)

Sessions & tokens

  • Launch token — a short-lived (60s), single-use token your backend mints to start a session for one player. Exchanged by the iframe for a session token.
  • Session token — the bearer credential the game app uses for all /api/play/* calls after session/init.
  • Bootstrap — the frozen snapshot returned at session/init: player, operator, theme, target box, fairness commitment, and policies. Pinned for the life of the session.

Money

  • Minor units — integer amounts in the currency’s smallest unit (amountMinor: 500 = €5.00).
  • Wallet RPC — the synchronous HMAC-signed call LootBox Solutions makes to your wallet for debit, credit, and balance. You implement it; your wallet is authoritative. See Operator configuration.
  • Idempotency key — a stable string per real-world money event. LootBox Solutions sends the same key (in the body and the Idempotency-Key header) on retries so your wallet can dedupe.

Purchase flows

LootBox Solutions supports two ways to play. The difference is when the box opens relative to payment.

  • Atomic buy & open — the player configures, sees the price, and commits. Debit, draw, and settle happen in one action. Not refundable — the outcome is realized immediately.

  • Pre-pay, open later — the player buys a box now (e.g. a “Buy now” widget button). The box rests unopened in their vault and is opened later. The outcome is drawn at open time. Cancellable/refundable while unopened, subject to policy.

  • Operator-funded open — your casino opens a box for a player without debiting their wallet (a free/bonus box). Casino-initiated and signed; LootBox Solutions doesn’t model bonuses — it trusts the instruction and skips the debit. See Purchase.

  • Vault — the player’s collection of bought-but-unopened boxes (distinct from inventory, which holds won prizes). A pre-bought box auto-opens when the player next lands on its page.

  • Reel — one box-open slot within a round, referencing a boxVersionId. Today a round opens a single box (maxReels is 1); reels is an array in the open request for forward compatibility.

Round lifecycle

A round is a unit of play. Its lifecycle:

created ─▶ (debit) ─▶ held ─▶ (open/draw) ─▶ settled
                │                                 ▲
                └─▶ voided (debit refused)        │
   held ─▶ (refund) ─▶ refunded ──────────────────┘ terminal
  • created — row pinned before the wallet is called (transient).
  • held — pre-paid, unopened (the vault state).
  • settled — opened and resolved; payout + won items materialized.
  • voided — the debit was refused; no money moved.
  • refunded — a held box that was cancelled; money credited back.

voided and refunded are distinct states on purpose: one means no money ever moved, the other means money moved and was returned. Don’t conflate them in reconciliation.

Fairness

  • Provably fair — every settled round is verifiable. LootBox Solutions commits to a hashed server seed up front; combined with your client seed and a per-player nonce, the outcome is reproducible and tamper-evident. See Fairness & verification.

Communication channels

  • S2S API — your backend → LootBox Solutions, HMAC-signed. See Server-to-server API.
  • Player API — game app → LootBox Solutions, bearer-authenticated. See Gameplay reference.
  • Wallet RPC — LootBox Solutions → your wallet, synchronous, blocks the player.
  • Webhooks / dispatcher — LootBox Solutions → your webhook receiver, async, retried.
  • postMessage — iframe ↔ host page, for balance, auth prompts, theme, navigation, and URL sync. See Host ↔ iframe messaging.