Skip to content
LootBox Solutions

Localization & currency

LootBox Solutions localizes both language (UI + content) and currency (prices + wallet). You declare the languages and currencies your brand supports, set them per session at launch, and can change them live without a reload.

Supported sets

Declare your supported locales and currencies in operator configuration. Launch and on-the-fly requests validate against these sets; an unsupported value is rejected (UNSUPPORTED_LOCALE / UNSUPPORTED_CURRENCY).

At launch

Pass locale and currency when you mint a launch token:

{ "playerExternalId": "u_8431", "gameKey": "mystery_box",
  "target": { "boxId": 42 }, "locale": "pt-BR", "currency": "BRL" }
  • locale — a BCP-47-ish code (en, pt-BR, de). Sets the game app UI language and the language of localized box/prize content.
  • currency — ISO 4217. Sets the currency prices are shown in and the currency LootBox Solutions debits/credits against your wallet.

Both are captured into the frozen bootstrap for the session.

On the fly

To change language or currency without reloading the iframe, send a host → iframe message:

send({ type: 'locale',   locale: 'de' });
send({ type: 'currency', currency: 'USD' });

The game app re-renders text, reformats numbers, and reprices the lobby and box prices in place. Use this to mirror a language/currency switcher that lives in your own chrome around the iframe.

What changes, and what doesn’t

  • Lobby and unopened box prices reprice to the new currency and relabel to the new language immediately.
  • The exchange rate is re-pinned on a currency change: the price shown after the switch and the amount the next purchase settles at are captured together, so they stay in lockstep. A rate quote is only valid for the currency it was established in.
  • Already-held (pre-paid) boxes stay locked to the currency and price they were bought in — a vault box can’t be repriced after purchase. The same applies to settled rounds.
  • The wallet currency for subsequent spends follows the new currency, so ensure the player has a balance in it on your side before switching.

If the exchange rate moves materially between the moment a price is shown and the moment the player buys — beyond the operator’s configured tolerance, or if the rate becomes unavailable — the open is refused with FX_RATE_MOVED and the game app re-quotes at the current price rather than settling at a stale one.

Multi-currency operators & pricing

A single operator can serve players in different currencies. Box prices are resolved per currency at display time:

  • The catalog returns priceMinor in the currency you request (?currency=…).
  • The currency on each amount in every API response tells you exactly what unit you’re looking at — never assume the operator default.

A box carries a single base price; prices in other currencies are derived by converting from that base via the operator’s configured FX rates. From the integration side you always read the resolved priceMinor + currency rather than computing it.

Your wallet receives every wallet.debit / wallet.credit in the currency the player is transacting in. LootBox Solutions converts the box price once, at purchase, and passes the final amount and currency through — your wallet records them as-is and never converts a second time. If the player changes currency mid-session, the next purchase’s wallet calls carry the new currency.

The same holds in reverse for item cashback: when a player cashes a won item back to balance, LootBox Solutions converts its value into the player’s wallet currency before the wallet.credit, so the credit arrives in the currency your wallet holds. The operator-currency amount and the rate travel in the credit’s reference for reconciliation.

Translated content & UI

  • UI — the game app ships translations for its own strings, selected by locale.
  • Content — box and prize names/descriptions are localized where a translation exists for the requested locale; otherwise they fall back to the operator’s default locale.

Request content in a specific language by setting locale at launch (or switching on the fly); the catalog and bootstrap return the best available translation per field.