Overview & architecture

LootBox Solutions powers mystery-box gameplay; your brand provides the player, the money, and the surrounding product. This page is the mental model the rest of the docs build on.

The contract in one screen

Your backend   ──HMAC──▶  POST /api/s2s/launches            (mint a session)
                          ◄─ { launchUrl, launchToken }
Your frontend  ─────────▶  <iframe src=launchUrl>           (renders /play)
Game app       ─────────▶  POST /api/play/session/init       (exchange token)
                          ◄─ { sessionToken, bootstrap }
Game app       ──bearer──▶  /api/play/rounds/open            (purchase / open)
                           /api/play/inventory/*             (won items)
                           /api/play/shipping/orders         (fulfillment)
                           /api/play/wallet/balance          (balance refresh)

Platform       ──HMAC──▶   POST {your wallet URL}            (you implement)
                           wallet.debit / wallet.credit / wallet.balance
Platform       ──HMAC──▶   POST {your webhook URL}           (you implement)
                           bonus / fulfillment / observational events

Alternatively, your backend can drive purchases, cashouts, cancels, and history directly through the Server-to-server API without relying on the in-iframe player surface. See Integration models.

Principles

• Identity is playerExternalId, end to end. You assign every player a stable opaque id in your system. LootBox Solutions never learns their name, email, or any PII — it only ever sees that id.
• Your wallet is authoritative. LootBox Solutions holds no balance. Every money movement (open a box, cash back a prize, refund) is a synchronous call to your wallet RPC, which accepts or refuses. If your wallet is unreachable, the player simply can’t spend — nothing is lost.
• One subdomain per operator. Your brand is an operator, reachable at https://{operator}.app.lootboxsolutions.com. All API paths below are relative to that host.
• Money is in minor units. Every amount is an integer in the currency’s smallest unit (e.g. 500 = €5.00). Currency travels with each amount.
• Sessions are frozen. When a play session starts, its configuration (box, price, theme, locale, currency) is pinned for the life of that session. Edits you make in admin affect new sessions, never a running one.

The pieces you operate

Piece	Who runs it	Purpose
S2S API	LootBox Solutions	Your backend calls it (HMAC-signed) to mint sessions, read the catalog, and drive purchases/cashouts/cancels/history.
Player iframe (/play)	LootBox Solutions	The embedded gameplay surface your players interact with.
Player API (/api/play)	LootBox Solutions	The bearer-authenticated surface the game app drives; also documented for native clients.
Your wallet RPC	You	LootBox Solutions calls it to debit/credit/read the player’s balance.
Your webhook receiver	You	LootBox Solutions posts async bonus/fulfillment + observational events here.

Two things you must stand up

Everything else is configuration, but these two are code you write:

1. A wallet endpoint that handles wallet.debit, wallet.credit, and wallet.balance. See Player API → wallet model and the request shapes in Operator configuration.
2. A webhook receiver for bonus entitlements, fulfillment notices, and the observational events you choose to subscribe to.

Next: Integration models to decide how much of the player experience you host yourself.