Core concepts
Tenants, brands, players, service modes, and the money model. Read this once.
Tenants vs brands
A tenant is your commercial account on WOWsino. A tenant owns one or more brands. Most operators have one brand per tenant (matching their public-facing site); white-label launchers can run several brands under one tenant.
| Concept | What it is |
|---|---|
tenant | The commercial entity (your company). Owns API keys, billing, contracts. |
brand | The player-facing identity (logo, domain, copy). One tenant → ≥1 brand. |
player | A real human account, scoped to a brand. Identified by (brand, username). |
operator | A user of your admin console — a member of your team. |
Service modes
| Mode | What you own | What we own |
|---|---|---|
| plug_in | Player accounts, real-money wallet, PSP, KYC, game aggregator, licensing | Engagement engines (bonuses, lootbox, raffles, jackpots, journeys, etc.), CRM, VIP, gamification |
| white_label | Licensing, PSP credentials, KYC vendor, marketing | Everything else — PAM, wallet, ledger, engines, compliance gate, audit, operator admin |
API keys: live vs test
Every tenant has two key families:
wsk_live_…— production. Real player ledger writes. Real Stripe-billable usage.wsk_test_…— sandbox. Same surface, isolated from live billing; safe for CI.
Keys carry scopes. Default scope * grants the full surface; restrict per integration as you mature.
The money model
Every monetary movement on WOWsino is a balanced, idempotent ledger entry. Balances are derived; the ledger is the source of truth.
Four asset rails:
| Rail | What it is | Convertible? |
|---|---|---|
real | Cash equivalent (USD, EUR, BTC, USDC, …) | Withdrawable per your PSP rules |
bonus | Locked promotional balance. Convertible to real after wagering | Convertible on fulfillment |
winz | Operator points granted by lootboxes, quests, campaigns, mini-games | Off-ledger by default; convert via your own redemption rules |
xp | VIP progression points. Daily-capped from real play only | Never withdrawable; drives level + cashback |
Idempotency
Every write endpoint accepts an idempotency_key in the body (or auto-generates one when you don't supply one). Re-sending the same request — for any reason, including network retries — returns the original result, never a duplicate side-effect.
POST /v1/lootbox/<id>/open
{
"user_id": "StarlordV7",
"idempotency_key": "open-2025-05-19-uniq-abc"
}
# First call: 201 with new reward
# Second call (same key): 200 with the SAME reward + "deduped": truePlayer resolution
Identify players by username within your brand. Your own internal UUID can be passed as external_ref on upsert and recovered from the player dossier later.