{"openapi":"3.0.3","info":{"title":"0Wallet Game Service API","description":"API documentation for Game Services, Catalog, Promotions, and Provider Credentials.\n\n**Architecture:** Laravel 13 + RoadRunner. The Laravel API layer handles REST requests and\ncommunicates with the Go game microservice via gRPC internally. Clients only interact with the\nLaravel REST endpoints documented here.\n\n**Authentication:** JWT Bearer token via `tymon/jwt-auth`.\n- User routes use the `auth:api` guard (issued at `/v1/user/login`).\n- Admin routes use the `auth:admin` guard (issued at `/v1/admin/login`).\n\n**Multi-tenancy:** Resolved via the `X-Tenant-Id` request header on every request.\n\n**Response envelope:** All responses use a standardised JSON envelope:\n```json\n{\n  \"status\": true,\n  \"message\": null,\n  \"data\": { ... }\n}\n```\nError responses:\n```json\n{\n  \"status\": false,\n  \"message\": \"Error description\",\n  \"code\": \"ERROR_CODE\"\n}\n```\nPaginated responses include a `meta` block:\n```json\n{\n  \"status\": true,\n  \"message\": null,\n  \"data\": [ ... ],\n  \"meta\": {\n    \"pagination\": {\n      \"total\": 50,\n      \"per_page\": 15,\n      \"current_page\": 1,\n      \"last_page\": 4,\n      \"from\": 1,\n      \"to\": 15,\n      \"has_more\": true\n    }\n  }\n}\n```\n\n**Datetime format:** All datetime fields use ISO 8601 / RFC 3339 format with timezone offset.\nUse `+08:00` for Malaysia time (e.g. `\"2026-02-26T00:00:00+08:00\"`).\n","version":"3.2.3"},"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://virtserver.swaggerhub.com/ndm-d07/0WalletServices66/3.2.3"},{"description":"SwaggerHub API Auto Mocking","url":"https://virtserver.swaggerhub.com/ndm-da0/0WalletServices/2.0.0"},{"url":"https://api.domain.com","description":"Staging Server"}],"tags":[{"name":"Catalog","description":"Service list, categories, providers, popular and recent"},{"name":"Game","description":"Launch service, restore balance, and synced balance"},{"name":"Bet History","description":"Player bet history records"},{"name":"Promotion (Admin)","description":"Admin CRUD for promotions and player claim records"},{"name":"Promotion (Player)","description":"Player-facing promotion listing and claiming"},{"name":"Promotion Category (Admin)","description":"Admin CRUD for promotion categories"},{"name":"Custom Category (Admin)","description":"Admin CRUD for custom lobby categories and item management"},{"name":"Provider Credential (Admin)","description":"Admin CRUD for provider credentials, schema, and connection testing"},{"name":"Provider Balance (Admin)","description":"Admin view, refresh, and withdraw for per-user provider balances"},{"name":"Service Restriction (Admin)","description":"Admin block/unblock for per-user provider and provider-category access"},{"name":"Game Provisioning (BO Central)","description":"Promote providers from tenant_acme into the central catalog and provision them per-tenant"},{"name":"Sales Rate (BO Central)","description":"Platform-wide sales rate defaults, daily kiosk snapshots, and per-tenant total IN/OUT reporting (auth:central)"},{"name":"Sales Rate (Admin)","description":"Per-tenant sales rate overrides that beat the central default (auth:admin)"}],"paths":{"/v1/user/service/list":{"get":{"tags":["Catalog"],"summary":"Get service list","description":"Retrieve list of services with optional filters.\nProxied to the Go game service via gRPC.\n","parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"provider_id","in":"query","description":"Filter by provider ID (optional)","schema":{"type":"integer"},"example":1},{"name":"category_id","in":"query","description":"Filter by service category ID (optional)","schema":{"type":"integer"},"example":5},{"name":"status","in":"query","description":"Filter by active status (optional)","schema":{"type":"boolean"},"example":true},{"name":"provider_category_ids","in":"query","description":"Filter by provider category IDs (optional, array)","schema":{"type":"array","items":{"type":"integer"}},"example":[1,2,3]},{"name":"provider_category_slug","in":"query","description":"Filter by brand slug (`provider_categories.slug`, e.g. `pp`) — unique per provider.\nEquivalent to the `{providerCategorySlug}` segment of the SEO route\n`GET /v1/user/{providerId}/{providerCategorySlug}/{serviceCategorySlug}`.\n","schema":{"type":"string"},"example":"pp"},{"name":"service_category_slug","in":"query","description":"Filter by service-category slug (`service_categories.slug`, e.g. `slot`,\n`live-casino`, `sportsbook`).\n","schema":{"type":"string"},"example":"slot"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeServiceListResponse"},"example":{"status":true,"message":null,"data":{"total":251,"services":[{"id":18,"providerId":1,"providerName":"jili","name":"Royal Fishing","serviceCode":"1","categoryId":5,"categoryName":"Fishing","iconUrl":"","status":true,"serviceTag":1,"maintenance":false,"providerCategoryId":2}]}}}}},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/user/{providerId}/{providerCategorySlug}/{serviceCategorySlug}":{"get":{"tags":["Catalog"],"summary":"Get service list (SEO path)","description":"SEO-friendly, query-string-free variant of `GET /v1/user/service/list`. Resolves a\nprovider + brand + service category from a clean URL path instead of query parameters,\nso the page is crawlable and shareable — e.g. `/v1/user/500001/pp/slot`.\n\nPath segments (`{providerId}/{providerCategorySlug}/{serviceCategorySlug}`):\n- `{providerId}` — numeric provider ID (e.g. `500001` = TheOne).\n- `{providerCategorySlug}` — the brand slug from `provider_categories.slug`, set via\n  BO Central `POST /v1/central/game-catalog/brand-slug`. Unique per provider (e.g. `pp`\n  for Pragmatic Play). Frontends read it from the `provider_category_slug` field on\n  grouped `provider_category` items in `GET /v1/user/service/categories`.\n- `{serviceCategorySlug}` — the service-category slug from `service_categories.slug`\n  (`sportsbook`, `live-casino`, `slot`, `table`, `fishing`, `crash`, `lottery`, `poker`,\n  `others`).\n\nFilters are equivalent to `provider_id` + `provider_category_slug` + `service_category_slug`\non `/v1/user/service/list`, and the response envelope is identical\n(`EnvelopeServiceListResponse`). No auth required (crawlers / SSR hit this); when the\ncaller is authenticated, favourites are sorted first.\n","parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"providerId","in":"path","required":true,"description":"Provider ID","schema":{"type":"integer"},"example":500001},{"name":"providerCategorySlug","in":"path","required":true,"description":"Brand slug on provider_categories.slug (unique per provider)","schema":{"type":"string"},"example":"pp"},{"name":"serviceCategorySlug","in":"path","required":true,"description":"Service-category slug on service_categories.slug","schema":{"type":"string"},"example":"slot"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeServiceListResponse"},"example":{"status":true,"message":null,"data":{"total":42,"services":[{"id":1001,"providerId":500001,"providerName":"theone","name":"Gates of Olympus","serviceCode":"vs20olympgate","categoryId":3,"categoryName":"Slot","iconUrl":"","status":true,"serviceTag":1,"maintenance":false,"providerCategoryId":3}]}}}}},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/user/service/categories":{"get":{"tags":["Catalog"],"summary":"Get categories","description":"Retrieve categories for the lobby.\nCustom categories (ordered by sort_order) are returned first, followed by default\nservice categories from the game service. If no custom categories exist, only defaults are returned.\n\n**Default service categories** also carry an `items` array — one entry per live\n`provider_category` belonging to that service category. The shape is simpler than the\ncustom-category items (no `type`, no `action`): `providerCategoryId`, `serviceCategoryId`,\n`name`, `providerId`, `walletType`, `iconUrl`, `sortOrder`. The cascade rule that hides\na default category when it has no live providers also applies to its items, so under the\nuser-facing default a returned category will always have ≥1 entry in `items`.\nFrontend behavior for these items mirrors `Flow 2` below — tap a tile → call\n`GET /service/list?provider_category_ids=[{providerCategoryId}]` → tap game → launch.\n\n**Custom categories** include `is_custom: true` and an `items` array. Each item has an\n`action` field telling the frontend what to do when the tab is tapped:\n\n| action | type | condition | meaning | what happens on tab tap |\n|--------|------|-----------|---------|------------------------|\n| `launch` | `service` | always (admin added a `service` directly) | Flat game tile, tap → launch | `POST /service/launch` with `service_id={id}` (or `provider_id` when `wallet_type=3`) |\n| `launch` | `service` | `provider_category` items, same aggregator | Flat game list (services embedded) | Tap game → `POST /service/launch` with `service_id={id}` |\n| `launch` | `service` | `provider` item, all child categories share same aggregator | Flat game list (services embedded — App-wallet always lands here, single tile) | Tap → launch |\n| `launch` | `service` | `provider_category` item with `wallet_type=3` or `service_category_id=1` (sportsbook) in a grouped category | App-wallet / sportsbook always launches directly — no game list | `POST /service/launch` with `service_id={id}` (or `provider_id` when `wallet_type=3`) |\n| `game_list` | `provider_category` | `provider_category` items, diff aggregators (non-app) | Grouped tiles, tap tile → game list | `GET /service/list?provider_category_ids=[{id}]` |\n| `game_list` | `provider_category` | `provider` item, child categories have different aggregators (e.g. tw_theone_agg) | One reference tile per child category | `GET /service/list?provider_category_ids=[{id}]` |\n| `game_list` | `service_category` | always | Reference tile, tap → game list | Uses existing categories/providers flow |\n\nEvery emitted item carries `wallet_type` (1=seamless, 2=transfer, 3=app) and\n`provider_id` (except `service_category` which has no wallet concept). When\n`wallet_type === 3`, the frontend should call Launch with `provider_id` for the\nApp-wallet shortcut and expect the 4-field response (login_url + username +\npassword + download_url).\n\n**Grouping rule for `provider_category` items:**\nWhen a custom category contains multiple `provider_category` items, the API checks their\n`provider_id` + `aggregator` combination. If all share the same combination → services are\nfetched and embedded as flat `type: \"service\"` items (Flow 1). If any differ → items are\nreturned as `type: \"provider_category\"` references for the frontend to resolve (Flow 2).\nExample: JILI SLOTS + PP SLOTS both under TheOne (provider_id=500001) are different aggregators\n(aggregator=2 vs aggregator=1) → grouped. JILI SLOTS + JILI LIVE under TheOne share the same\naggregator → flat, all games merged.\n\n**Frontend flows:**\n\n**Flow 1 — Flat game list (same aggregator):** Services embedded, tap to launch.\n`[PP] tab → game list: [Baccarat] [Gameshows] → tap game → launch (POST /service/launch)`\n\n**Flow 2 — Grouped `provider_category` (diff aggregators, non-app):** Tiles first, then game list.\n`[theone] tab → tiles: [PP LIVE] [JILI LIVE] → tap PP LIVE → game list (GET /service/list?provider_category_ids=[3]) → launch`\nEach grouped item also carries `provider_category_slug` (brand slug), so the tile can link to the\nSEO path `GET /v1/user/{provider_id}/{provider_category_slug}/{service_category_slug}` (e.g.\n`/v1/user/500001/pp/slot`) instead of the query-string `GET /service/list?provider_category_ids=[…]`.\n\n**Flow 2a — Grouped `provider_category` with `wallet_type=3` or sportsbook (`service_category_id=1`):** App-wallet / sportsbook tile in a mixed category resolves to direct launch (no game list step).\n`[mixed] tab → tiles: [918KISS tile (action:launch)] [PP SLOTS tile (action:game_list)] → tap 918KISS → launch (POST /service/launch with provider_id)`\n`[mixed] tab → tiles: [CMD Sports tile (action:launch)] [PP SLOTS tile (action:game_list)] → tap CMD Sports → launch (POST /service/launch with service_id)`\n\n**Flow 3 — `service_category` (`action: game_list`):** Reference tile, frontend uses existing flow.\n`[Featured] tab → tiles: [Live Casino] [Slots] → tap Live Casino → existing categories/providers flow`\n\n**Flow 4 — `service` (`action: launch`):** Direct game tiles, tap to launch.\n`[Featured] tab → tiles: [Fortune Tiger] → tap → launch (POST /service/launch)`\n","parameters":[{"$ref":"#/components/parameters/XTenantId"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeCategoriesResponse"},"examples":{"with_custom_categories":{"summary":"Custom categories first, then defaults appended","value":{"status":true,"message":null,"data":{"categories":[{"id":1,"name":"PP","slug":"pp","iconUrl":"https://r2.example.com/custom-categories/pp.png","activeIconUrl":"https://r2.example.com/custom-categories/pp-active.png","sort_order":0,"is_custom":true,"items":[{"type":"service","id":601,"name":"Baccarat Lobby","icon_url":"https://example.com/games/baccarat.jpg","provider_category_id":3,"wallet_type":1,"provider_id":1,"sort_order":0,"action":"launch"},{"type":"service","id":607,"name":"Gameshows","icon_url":"https://example.com/games/gameshows.jpg","provider_category_id":3,"wallet_type":1,"provider_id":1,"sort_order":0,"action":"launch"},{"type":"service","id":101,"name":"Fortune Tiger","icon_url":"https://r2.example.com/services/fortune-tiger.png","provider_category_id":7,"wallet_type":1,"provider_id":2,"sort_order":1,"action":"launch"}]},{"id":2,"name":"theone - All","slug":"theone-all","iconUrl":"https://r2.example.com/custom-categories/theone.png","activeIconUrl":null,"sort_order":1,"is_custom":true,"items":[{"type":"provider_category","id":3,"name":"PP - LIVE","wallet_type":1,"provider_id":5,"provider_category_slug":"pp","sort_order":0,"action":"game_list"},{"type":"provider_category","id":5,"name":"JILI - LIVE","wallet_type":1,"provider_id":1,"provider_category_slug":"jili","sort_order":1,"action":"game_list"}]},{"id":3,"name":"Live","slug":"live","iconUrl":"https://r2.example.com/custom-categories/live.png","activeIconUrl":null,"sort_order":2,"is_custom":true,"items":[{"type":"service_category","id":2,"name":"Live Casino","icon_url":"https://r2.example.com/service-categories/live.png","sort_order":0,"action":"game_list"}]},{"id":4,"name":"Casino Apps","slug":"casino-apps","iconUrl":"https://r2.example.com/custom-categories/apps.png","activeIconUrl":null,"sort_order":3,"is_custom":true,"items":[{"type":"service","id":8001,"name":"lobbykiss","icon_url":"https://r2.example.com/services/lobbykiss.png","provider_category_id":100,"wallet_type":3,"provider_id":500003,"sort_order":0,"action":"launch"},{"type":"service","id":8002,"name":"Pussy888","icon_url":"https://r2.example.com/services/pussy888.png","provider_category_id":101,"wallet_type":3,"provider_id":500004,"sort_order":1,"action":"launch"}]},{"id":1,"name":"Sports / E-sports","slug":"sports-esports","iconUrl":"","activeIconUrl":"","status":true,"sortOrder":0,"items":[{"providerCategoryId":12,"serviceCategoryId":1,"name":"SBO - SPORTS","providerId":7,"walletType":2,"iconUrl":"https://r2.example.com/provider-categories/sbo-sports.png","sortOrder":0}]},{"id":2,"name":"Live Casino","slug":"live-casino","iconUrl":"","activeIconUrl":"","status":true,"sortOrder":1,"items":[{"providerCategoryId":1,"serviceCategoryId":2,"name":"PRAGMATIC PLAY - LIVE","providerId":1,"walletType":2,"iconUrl":"https://r2.example.com/provider-categories/pp-live.png","sortOrder":0},{"providerCategoryId":6,"serviceCategoryId":2,"name":"ONGAMING - LIVE CASINO","providerId":500003,"walletType":1,"iconUrl":"","sortOrder":1}]}]}}},"without_custom_categories":{"summary":"No custom categories — defaults only, each with provider_category items","value":{"status":true,"message":null,"data":{"categories":[{"id":1,"name":"Sports / E-sports","slug":"sports-esports","iconUrl":"","activeIconUrl":"","status":true,"sortOrder":0,"items":[{"providerCategoryId":12,"serviceCategoryId":1,"name":"SBO - SPORTS","providerId":7,"walletType":2,"iconUrl":"https://r2.example.com/provider-categories/sbo-sports.png","sortOrder":0}]}]}}}}}}},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/user/service/providers":{"get":{"tags":["Catalog"],"summary":"Get providers","description":"Retrieve list of providers. Providers with `isEvent: true` are event providers — they are\nreturned to everyone, but are only launchable by players with an active in-progress promotion.\nThe frontend should grey out event providers/categories for guests and non-promotion users\n(using the `/v1/user/service/active-game` result), mirroring the existing eligibility greying.\n","parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"status","in":"query","description":"Filter providers by active status (optional)","schema":{"type":"boolean"},"example":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeProviderListResponse"},"examples":{"mixed":{"summary":"Mix of transfer-wallet and App-wallet providers — note `walletType` per provider","value":{"status":true,"message":null,"data":{"total":3,"providers":[{"id":1,"name":"jili","code":"jili","activeIconUrl":"","iconUrl":"","status":true,"walletType":1,"isEvent":false,"categories":[{"providerCategoryId":2,"name":"JILI - FISHING","serviceCategoryId":5,"iconUrl":""},{"providerCategoryId":1,"name":"JILI - SLOTS","serviceCategoryId":3,"iconUrl":""}]},{"id":500003,"name":"YES918","code":"yes918_app","activeIconUrl":"","iconUrl":"https://r2.example.com/providers/yes918.png","status":true,"walletType":3,"isEvent":true,"categories":[{"providerCategoryId":100,"name":"lobbykiss","serviceCategoryId":9,"iconUrl":""}]},{"id":500004,"name":"PUSSY888","code":"pussy888","activeIconUrl":"","iconUrl":"https://r2.example.com/providers/pussy888.png","status":true,"walletType":3,"isEvent":false,"categories":[{"providerCategoryId":101,"name":"Pussy888","serviceCategoryId":9,"iconUrl":""}]}]}}}}}}},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/user/service/provider-categories":{"get":{"tags":["Catalog"],"summary":"Get provider categories","description":"Retrieve provider categories with optional provider filter","parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"provider_id","in":"query","description":"Filter by provider ID (optional)","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeProviderCategoriesResponse"},"example":{"status":true,"message":null,"data":{"total":3,"categories":[{"id":1,"name":"JILI - SLOTS","provider_id":1,"provider_name":"JILI","service_category_id":3,"category_name":"Slots","status":true,"icon_url":"","wallet_type":1,"sort_order":0,"aggregator":"0","is_event":false,"is_iframe":true,"slug":"jili"},{"id":5,"name":"PRAGMATIC PLAY - LIVE","provider_id":500001,"provider_name":"THEONE","service_category_id":2,"category_name":"Live Casino","status":true,"icon_url":"","wallet_type":2,"sort_order":0,"aggregator":"5","is_event":false,"is_iframe":null,"slug":"pp"},{"id":101,"name":"Pussy888","provider_id":500004,"provider_name":"Pussy888","service_category_id":9,"category_name":"Casino App","status":true,"icon_url":"","wallet_type":3,"sort_order":0,"aggregator":"0","is_event":false,"is_iframe":null,"slug":"pussy888"}]}}}}},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/user/service/popular":{"get":{"tags":["Catalog"],"summary":"Get popular services","description":"Retrieve most played services ranked by total plays","parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"limit","in":"query","description":"Max number of results (optional, default 10)","schema":{"type":"integer","default":10},"example":10}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopePopularServicesResponse"},"example":{"status":true,"message":null,"data":{"total":2,"services":[{"id":18,"providerId":1,"providerName":"jili","name":"Royal Fishing","serviceCode":"1","categoryId":5,"categoryName":"Fishing","iconUrl":"","status":true,"serviceTag":1,"maintenance":false,"totalPlays":150}]}}}}},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/user/service/recent":{"get":{"tags":["Catalog"],"summary":"Get recent services","description":"Retrieve user's recently played services ordered by last played time.\nRequires authentication.\n","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"limit","in":"query","description":"Max number of results (optional, default 10)","schema":{"type":"integer","default":10},"example":10}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeRecentServicesResponse"},"example":{"status":true,"message":null,"data":{"total":1,"services":[{"id":18,"providerId":1,"providerName":"jili","name":"Royal Fishing","serviceCode":"1","categoryId":5,"categoryName":"Fishing","iconUrl":"","status":true,"serviceTag":1,"maintenance":false,"lastPlayedAt":"2026-02-26T00:00:00+08:00"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/user/service/active-game":{"get":{"tags":["Catalog"],"summary":"Get active game eligibility","description":"Returns the user's current active promotion with allowed provider category and category IDs,\nplus `blockedProviderCategoryIds` — event-provider categories (is_event) the user may NOT\ncurrently play. Frontend uses the allowed lists to grey out ineligible providers/categories,\nand additionally greys any tile whose provider_category is in `blockedProviderCategoryIds`\n(independent of the allow-list). The response is also returned for users WITHOUT a promotion\nwhen there are event categories to block — in that case `promotionId` is null and the allowed\nlists are empty. It is only null when there is no promotion AND nothing to block.\n","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"examples":{"with_promotion":{"summary":"User has active promotion (event categories not in the promotion are blocked)","value":{"status":true,"message":null,"data":{"activeGame":{"promotionId":1,"promotionName":"Welcome Bonus","allowedProviderCategoryIds":[1,3],"allowedCategoryIds":[1],"blockedProviderCategoryIds":[96,97]}}}},"no_promotion_with_event_block":{"summary":"No promotion, but event providers exist — blocked so the frontend dims them","value":{"status":true,"message":null,"data":{"activeGame":{"promotionId":null,"promotionName":null,"allowedProviderCategoryIds":[],"allowedCategoryIds":[],"blockedProviderCategoryIds":[96,97]}}}},"no_promotion":{"summary":"No active promotion and no event categories to block","value":{"status":true,"message":null,"data":{"activeGame":null}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/user/service/launch":{"post":{"tags":["Game"],"summary":"Launch service","description":"Launch a game/service session for the authenticated user.\nUser is identified from the JWT token. Amount is optional (defaults to full wallet balance for transfer providers).\n","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"requestBody":{"required":true,"description":"Launch request body. **Exactly one** of `service_id` or `provider_id` must be set\n(see `LaunchServiceRequest` schema for the full rule).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchServiceRequest"},"examples":{"transfer_or_seamless":{"summary":"Transfer/seamless wallet — pick a specific game by service_id","value":{"service_id":10,"amount":"100.00"}},"app_wallet_by_provider":{"summary":"App-wallet (wallet_type=3) — provider_id shortcut, no game list","value":{"provider_id":500003,"amount":"100.00"}}}}}},"responses":{"200":{"description":"Launch successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeLaunchServiceResponse"},"examples":{"seamless_transfer":{"summary":"Seamless or transfer provider","value":{"status":true,"message":null,"data":{"login_url":"https://game.jili.com/launch/abc123"}}},"app_provider":{"summary":"App-type provider (wallet_type 3) — deep link + credentials","value":{"status":true,"message":null,"data":{"login_url":"lobbykiss://lobbykiss?account=A1004&password=Abc123","username":"A1004","password":"Abc123","download_url":"https://cdn.provider.com/app.apk"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/user/service/restore-balance":{"post":{"tags":["Game"],"summary":"Restore balance","description":"Withdraw balance from provider and credit back to the authenticated user's wallet.\nUser is identified from the JWT token.\n","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"requestBody":{"required":false,"description":"Restore balance request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestoreBalanceRequest"},"example":{"provider_id":1}}}},"responses":{"200":{"description":"Balance restored successfully","content":{"application/json":{"example":{"status":true,"message":null,"data":{"message":"Balance restored successfully","balance":"120.50"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/user/wallet/synced-balance":{"get":{"tags":["Game"],"summary":"Get synced balance","description":"Returns the balance for frontend display.\n- If the user has an active game session (transfer provider): calls provider's live GetBalance and returns it.\n- If no active session: returns real_bal from the wallet.\n\nThis ensures the frontend always shows the correct balance regardless of where funds are (wallet or provider).\n","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"responses":{"200":{"description":"Balance retrieved successfully","content":{"application/json":{"example":{"status":true,"message":null,"data":{"balance":"150.50"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/user/service/bet-history":{"get":{"tags":["Bet History"],"summary":"Get bet history","description":"Retrieve bet history records for the authenticated user","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"start_date","in":"query","description":"Start date filter (YYYY-MM-DD, defaults to 7 days ago)","schema":{"type":"string"},"example":"2026-03-01"},{"name":"end_date","in":"query","description":"End date filter (YYYY-MM-DD, defaults to today)","schema":{"type":"string"},"example":"2026-03-05"},{"name":"limit","in":"query","description":"Max records to return (default 100)","schema":{"type":"integer"},"example":100},{"name":"offset","in":"query","description":"Offset for pagination (default 0)","schema":{"type":"integer"},"example":0}],"responses":{"200":{"description":"Bet history records","content":{"application/json":{"example":{"status":true,"message":null,"data":{"total":20,"records":[{"theoneId":"831399640","betId":"8553_1_831399640000","gameCode":"vs20olympgate","gameName":"Gates of Olympus","providerCategoryName":"Pragmatic Play","product":"SL","betAmount":"40.0000","payoutAmount":"25.2400","winLoss":"-14.7600","betTime":"2026-03-03T14:38:28+08:00","settleTime":"2026-03-03T14:40:51+08:00","status":"S"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/bet-user-daily-summaries":{"get":{"tags":["Bet History"],"summary":"Get per-user daily bet rollups","description":"Returns daily aggregated bet stats from `bet_user_daily_summaries`, optionally\ngrouped server-side. Backed by the Go service's nightly aggregation cron, so\nsame-day data may lag by up to one day.\n\n**Decimal columns** (`total_*_amount`, `total_win_loss`, `total_valid_turnover`,\njackpot fields) are returned as strings to preserve precision.\n\n**`provider_category_id` and `summary_date`** are omitted from a row when the\nchosen `group_by` collapses that dimension (so the caller can distinguish a\ngrouped row from a real category-0 row).\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"date_from","in":"query","required":true,"description":"Inclusive start date (YYYY-MM-DD, UTC).","schema":{"type":"string"},"example":"2026-05-01"},{"name":"date_to","in":"query","required":true,"description":"Inclusive end date (YYYY-MM-DD, UTC). Window must not exceed 366 days.","schema":{"type":"string"},"example":"2026-05-04"},{"name":"user_ids","in":"query","description":"Optional. Repeat the param to filter to a set of users. Empty = all users.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"provider_category_ids","in":"query","description":"Optional. Repeat the param to filter to a set of provider categories. Empty = all categories.","schema":{"type":"array","items":{"type":"integer","format":"int64"}},"style":"form","explode":true},{"name":"group_by","in":"query","description":"Server-side aggregation level. Default = `RAW`.\n* `RAW` — one row per `(user_id, provider_category_id, summary_date)`.\n* `USER_DATE` — collapse across category, one row per `(user_id, summary_date)`.\n* `USER` — collapse across category and date, one row per `user_id`.\n","schema":{"type":"string","enum":["BET_USER_DAILY_SUMMARY_GROUP_BY_RAW","BET_USER_DAILY_SUMMARY_GROUP_BY_USER_DATE","BET_USER_DAILY_SUMMARY_GROUP_BY_USER"]},"example":"BET_USER_DAILY_SUMMARY_GROUP_BY_USER_DATE"}],"responses":{"200":{"description":"Daily summary rows. The shape of each row depends on `group_by`:\n\n* `RAW` — every field set, including `provider_category_id` and `summary_date`.\n* `USER_DATE` — `provider_category_id` omitted (row spans multiple categories).\n* `USER` — `provider_category_id` AND `summary_date` both omitted.\n","content":{"application/json":{"examples":{"raw":{"summary":"group_by=RAW (default)","value":{"status":true,"message":null,"data":{"rows":[{"user_id":"usr_alice","provider_category_id":1,"summary_date":"2026-05-04","total_bets":3,"total_bet_amount":"300.0000","total_payout_amount":"250.0000","total_win_loss":"-50.0000","total_win_amount":"100.0000","total_loss_amount":"150.0000","total_valid_turnover":"300.0000","total_jackpot_contribution":"0.0000","total_jackpot_win":"0.0000"},{"user_id":"usr_alice","provider_category_id":2,"summary_date":"2026-05-04","total_bets":2,"total_bet_amount":"1000.0000","total_payout_amount":"1200.0000","total_win_loss":"200.0000","total_win_amount":"300.0000","total_loss_amount":"100.0000","total_valid_turnover":"1000.0000","total_jackpot_contribution":"0.0000","total_jackpot_win":"0.0000"}]}}},"user_date":{"summary":"group_by=USER_DATE (provider_category_id omitted)","value":{"status":true,"message":null,"data":{"rows":[{"user_id":"usr_alice","summary_date":"2026-05-04","total_bets":5,"total_bet_amount":"1300.0000","total_payout_amount":"1450.0000","total_win_loss":"150.0000","total_win_amount":"400.0000","total_loss_amount":"250.0000","total_valid_turnover":"1300.0000","total_jackpot_contribution":"0.0000","total_jackpot_win":"0.0000"}]}}},"user":{"summary":"group_by=USER (both provider_category_id and summary_date omitted)","value":{"status":true,"message":null,"data":{"rows":[{"user_id":"usr_alice","total_bets":12,"total_bet_amount":"2700.0000","total_payout_amount":"2850.0000","total_win_loss":"150.0000","total_win_amount":"780.0000","total_loss_amount":"590.0000","total_valid_turnover":"2700.0000","total_jackpot_contribution":"0.0000","total_jackpot_win":"0.0000"}]}}}}}}},"400":{"description":"Invalid input (missing/malformed date, window > 366 days, etc.)"},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/bet-history-summaries":{"get":{"tags":["Bet History"],"summary":"Get platform-level bet summary leaderboards","description":"Returns aggregated rows from `bet_history_summaries` (per-game daily\nrollups, no per-user data) with optional server-side `group_by`,\n`sort_by`, and `sort_dir`. Supports two response shapes:\n\n* **Top-N mode** — pass `limit` (1..100). Server returns up to `limit`\n  rows ordered by `sort_by` and OMITS the `pagination` block. Use this\n  for leaderboard widgets (\"top 10 most-played games\", \"biggest payout\n  games this week\", etc.).\n* **Paginated mode** — leave `limit` unset and pass `page` + `page_size`\n  (1..200, default 20). Server returns the page plus a `pagination`\n  block with `total` / `total_pages`. Use this for browsable admin\n  tables.\n\n**Decimal columns** (`total_*_amount`, `total_win_loss`,\n`total_valid_turnover`, jackpot fields) are returned as strings to\npreserve precision.\n\n**`game_code`, `game_name`, `provider_category_id`, `summary_date`** are\nomitted from a row when the chosen `group_by` collapses that dimension\n(so the caller can distinguish a grouped row from a real value).\n\nBacked by the Go service's nightly aggregation cron, so same-day data\nmay lag by up to one day.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"date_from","in":"query","required":true,"description":"Inclusive start date (YYYY-MM-DD, UTC).","schema":{"type":"string"},"example":"2026-04-01"},{"name":"date_to","in":"query","required":true,"description":"Inclusive end date (YYYY-MM-DD, UTC). Window must not exceed 366 days.","schema":{"type":"string"},"example":"2026-04-30"},{"name":"provider_id","in":"query","description":"Optional. Filter to one provider.","schema":{"type":"integer","format":"int64"}},{"name":"provider_category_id","in":"query","description":"Optional. Filter to one provider category.","schema":{"type":"integer","format":"int64"}},{"name":"game_code","in":"query","description":"Optional. Exact match on `game_code`.","schema":{"type":"string"}},{"name":"search","in":"query","description":"Optional. ILIKE `%term%` across `game_code` and `game_name` JSONB text.","schema":{"type":"string"}},{"name":"group_by","in":"query","description":"Server-side aggregation level. Default = `RAW`.\n* `RAW` — one row per `(provider_id, game_code, provider_category_id, summary_date)`.\n* `GAME` — collapse `summary_date`; one row per `(provider_id, game_code, provider_category_id)`.\n* `CATEGORY` — collapse `game_code` and `summary_date`; one row per `(provider_id, provider_category_id)`.\n* `PROVIDER` — collapse all but `provider_id`.\n","schema":{"type":"string","enum":["BET_HISTORY_SUMMARY_GROUP_BY_RAW","BET_HISTORY_SUMMARY_GROUP_BY_GAME","BET_HISTORY_SUMMARY_GROUP_BY_CATEGORY","BET_HISTORY_SUMMARY_GROUP_BY_PROVIDER"]},"example":"BET_HISTORY_SUMMARY_GROUP_BY_GAME"},{"name":"sort_by","in":"query","description":"Sort key. Default = `TOTAL_BETS` (most-played).\nAll values map to a SUM-aggregated column.\n","schema":{"type":"string","enum":["BET_HISTORY_SUMMARY_SORT_BY_TOTAL_BETS","BET_HISTORY_SUMMARY_SORT_BY_TOTAL_BET_AMOUNT","BET_HISTORY_SUMMARY_SORT_BY_TOTAL_PAYOUT_AMOUNT","BET_HISTORY_SUMMARY_SORT_BY_TOTAL_WIN_LOSS","BET_HISTORY_SUMMARY_SORT_BY_TOTAL_VALID_TURNOVER","BET_HISTORY_SUMMARY_SORT_BY_TOTAL_JACKPOT_CONTRIB","BET_HISTORY_SUMMARY_SORT_BY_TOTAL_JACKPOT_WIN"]},"example":"BET_HISTORY_SUMMARY_SORT_BY_TOTAL_BETS"},{"name":"sort_dir","in":"query","description":"Sort direction. Default = `DESC` (top-N leaderboards).","schema":{"type":"string","enum":["BET_HISTORY_SUMMARY_SORT_DIR_DESC","BET_HISTORY_SUMMARY_SORT_DIR_ASC"]},"example":"BET_HISTORY_SUMMARY_SORT_DIR_DESC"},{"name":"limit","in":"query","description":"Top-N mode. When set (1..100), server returns up to `limit` rows\nand OMITS the `pagination` block. Mutually exclusive with\n`page` / `page_size`.\n","schema":{"type":"integer","minimum":1,"maximum":100},"example":10},{"name":"page","in":"query","description":"Paginated mode. 1-based page index. Ignored when `limit` is set.","schema":{"type":"integer","minimum":1},"example":1},{"name":"page_size","in":"query","description":"Paginated mode. 1..200, default 20. Ignored when `limit` is set.","schema":{"type":"integer","minimum":1,"maximum":200},"example":20}],"responses":{"200":{"description":"Summary rows. The shape of each row depends on `group_by`:\n\n* `RAW` — every field set, including `game_code`, `game_name`,\n  `provider_category_id`, `summary_date`.\n* `GAME` — `summary_date` omitted (collapsed across dates).\n* `CATEGORY` — `game_code`, `game_name`, AND `summary_date` omitted.\n* `PROVIDER` — `game_code`, `game_name`, `provider_category_id`,\n  AND `summary_date` all omitted.\n\nThe `pagination` block is present only in paginated mode (when the\ncaller did not supply `limit`).\n","content":{"application/json":{"examples":{"top_n_most_played":{"summary":"Top 10 most-played games (limit=10, group_by=GAME, sort_by=TOTAL_BETS)","value":{"status":true,"message":null,"data":{"rows":[{"provider_id":8553,"game_code":"vs20olympgate","game_name":"{\"en\":\"Gates of Olympus\",\"zh\":\"奥林匹斯之门\"}","provider_category_id":1,"total_bets":12403,"total_bet_amount":"498200.0000","total_payout_amount":"471050.0000","total_win_loss":"-27150.0000","total_valid_turnover":"498200.0000","total_jackpot_contribution":"0.0000","total_jackpot_win":"0.0000"},{"provider_id":8553,"game_code":"vs20doghouse","game_name":"{\"en\":\"The Dog House\",\"zh\":\"狗狗之家\"}","provider_category_id":1,"total_bets":9821,"total_bet_amount":"320500.0000","total_payout_amount":"298100.0000","total_win_loss":"-22400.0000","total_valid_turnover":"320500.0000","total_jackpot_contribution":"0.0000","total_jackpot_win":"0.0000"}]}}},"paginated_by_game":{"summary":"Paginated browse by game (page=1, page_size=20, group_by=GAME)","value":{"status":true,"message":null,"data":{"rows":[{"provider_id":8553,"game_code":"vs20olympgate","game_name":"{\"en\":\"Gates of Olympus\"}","provider_category_id":1,"total_bets":12403,"total_bet_amount":"498200.0000","total_payout_amount":"471050.0000","total_win_loss":"-27150.0000","total_valid_turnover":"498200.0000","total_jackpot_contribution":"0.0000","total_jackpot_win":"0.0000"}],"pagination":{"page":1,"page_size":20,"total":137,"total_pages":7}}}},"category":{"summary":"group_by=CATEGORY (game_code/game_name/summary_date omitted)","value":{"status":true,"message":null,"data":{"rows":[{"provider_id":8553,"provider_category_id":1,"total_bets":48211,"total_bet_amount":"1820000.0000","total_payout_amount":"1700500.0000","total_win_loss":"-119500.0000","total_valid_turnover":"1820000.0000","total_jackpot_contribution":"0.0000","total_jackpot_win":"0.0000"},{"provider_id":8553,"provider_category_id":2,"total_bets":9120,"total_bet_amount":"640000.0000","total_payout_amount":"612000.0000","total_win_loss":"-28000.0000","total_valid_turnover":"640000.0000","total_jackpot_contribution":"0.0000","total_jackpot_win":"0.0000"}]}}},"provider":{"summary":"group_by=PROVIDER (only provider_id retained)","value":{"status":true,"message":null,"data":{"rows":[{"provider_id":8553,"total_bets":57331,"total_bet_amount":"2460000.0000","total_payout_amount":"2312500.0000","total_win_loss":"-147500.0000","total_valid_turnover":"2460000.0000","total_jackpot_contribution":"0.0000","total_jackpot_win":"0.0000"}]}}}}}}},"400":{"description":"Invalid input (missing/malformed date, window > 366 days, etc.)"},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/user/promotions":{"get":{"tags":["Promotion (Player)"],"summary":"List active promotions","description":"Retrieve all currently active promotions grouped by promotion category.\nReturns an array of promotion categories, each with a nested `promotions` array.\nIf authenticated, each promotion includes an `is_claimable` flag.\nUnauthenticated users see `is_claimable: true` for all promotions.\n\nSome internal fields are hidden from this response (max_payout, max_withdrawal,\nturnover, winover, claim_condition_type, etc.).\n","parameters":[{"$ref":"#/components/parameters/XTenantId"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":"01HXY...","name":"Welcome Bonus","description":"Welcome bonus promotions for new players","sort_order":0,"banner_url":"https://cdn.example.com/category-banner.png","status":1,"promotions":[{"id":"01HXY...","title":"Welcome Bonus 100%","description":"Get 100% bonus on your first deposit","terms_conditions":"Minimum deposit 100. Max bonus 5000.","bonus_type":1,"bonus_value":100,"claim_conditions":{"min_deposit":100},"start_date":"2026-01-01T00:00:00+08:00","end_date":"2026-12-31T23:59:59+08:00","provider_category_ids":[1,3,5],"banner_image_url":"promotions/abc123.png","promo_image_url":"promotions/xyz789.png","promotion_category_id":"01HXY...","display_type":1,"display_description_only":false,"display_angpao_text":false,"turnover_winover_type":1,"created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T00:00:00+08:00","is_claimable":true}]}]}}}},"500":{"description":"Internal server error"}}}},"/v1/user/promotions/{id}/claim":{"post":{"tags":["Promotion (Player)"],"summary":"Claim a promotion","description":"Claim a promotion for the authenticated player. Flow:\n1. Validates promotion is active and not expired\n2. Checks player has not already claimed (or has remaining claims)\n3. Validates claim eligibility (e.g. minimum deposit for deposit-type conditions)\n4. Calculates bonus (percentage of balance or fixed amount, capped at max_payout)\n5. Debits player real_bal to 0 and credits bonus_bal (real_bal + bonus)\n6. Creates bonus record with wagering requirement and max_withdrawal cap\n","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"description":"Promotion ID (ULID)","schema":{"type":"string"},"example":"01HXY..."}],"responses":{"201":{"description":"Promotion claimed successfully","content":{"application/json":{"example":{"status":true,"message":"Resource created.","data":{"record_id":"01HXY...","bonus_amount":100,"message":"Promotion claimed successfully."}}}}},"404":{"description":"Promotion not found"},"422":{"description":"Claim failed. Possible reasons:\n- promotion is not active or has expired\n- already claimed this promotion\n- insufficient balance / minimum deposit required\n"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/user/promotions/active":{"get":{"tags":["Promotion (Player)"],"summary":"Get active promotion","description":"Return the authenticated user's current in-progress promotion, if any.\nUsed by frontend to show bonus progress.\n","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"examples":{"with_promotion":{"summary":"User has active promotion","value":{"status":true,"message":null,"data":{"has_active":true,"record_id":"01HXY...","promotion_title":"Welcome Bonus 100%","bonus_amount":100,"target_turnover":4000,"current_turnover":1500.5,"max_withdrawal":5000,"is_clearable":false,"claimed_at":"2026-02-26T00:00:00+08:00"}}},"no_promotion":{"summary":"No active promotion","value":{"status":true,"message":null,"data":{"has_active":false}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/admin/promotions":{"get":{"tags":["Promotion (Admin)"],"summary":"List promotions (admin)","description":"Paginated list of promotions with search and status filter.\nAdmin authentication required.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"search","in":"query","description":"Search by title (optional)","schema":{"type":"string"},"example":"Welcome"},{"name":"status","in":"query","description":"Filter by status: 0=inactive, 1=active (optional)","schema":{"type":"integer","enum":[0,1]},"example":1},{"name":"promotion_category_id","in":"query","description":"Filter by promotion category ID (optional)","schema":{"type":"string"},"example":"01HXY..."},{"name":"per_page","in":"query","description":"Items per page (default 15)","schema":{"type":"integer","default":15},"example":15},{"name":"page","in":"query","description":"Page number","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Successful paginated response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":"01HXY...","title":"Welcome Bonus 100%","description":"Get 100% bonus on your first deposit","bonus_type":1,"bonus_value":100,"max_payout":5000,"max_withdrawal":50,"claim_condition_type":1,"status":1,"sort_order":0,"promotion_category_id":"01HXY...","display_type":1,"created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T00:00:00+08:00","category":{"id":"01HXY...","name":"Welcome Bonus"}}],"meta":{"pagination":{"total":5,"per_page":15,"current_page":1,"last_page":1,"from":1,"to":5,"has_more":false}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Promotion (Admin)"],"summary":"Create promotion","description":"Create a new promotion. Admin authentication required.\nSupports file upload for banner and promo images via multipart/form-data.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"requestBody":{"required":true,"description":"Promotion creation payload (multipart/form-data to support image uploads)","content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/StorePromotionRequest"}}}},"responses":{"201":{"description":"Promotion created successfully","content":{"application/json":{"example":{"status":true,"message":"Resource created.","data":{"id":"01HXY...","title":"Welcome Bonus 100%","description":"Get 100% bonus on your first deposit","bonus_type":1,"bonus_value":100,"status":1}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"description":"Validation failed"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/admin/promotions/condition-template":{"get":{"tags":["Promotion (Admin)"],"summary":"Get claim condition template","description":"Returns the available claim condition fields for a given condition type.\nFrontend uses this to dynamically render a form for admin to configure claim conditions.\n\nIf `claim_condition_type` is provided, returns fields for that specific type.\nIf omitted, returns all universal fields and all condition-type-specific fields.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"in":"query","name":"claim_condition_type","schema":{"type":"integer","enum":[1,2,3]},"description":"1 = Deposit\n2 = Free\n3 = Custom\n"}],"responses":{"200":{"description":"Condition template fields","content":{"application/json":{"examples":{"specific_type":{"summary":"With claim_condition_type=1","value":{"status":true,"message":null,"data":{"claim_condition_type":1,"fields":[{"key":"min_deposit","label":"Min Deposit","fieldType":"number","required":true,"options":[]},{"key":"excluded_users","label":"Excluded Users","fieldType":"multi_input","required":false,"options":[]}]}}},"all_types":{"summary":"Without claim_condition_type","value":{"status":true,"message":null,"data":{"universal_fields":[],"condition_type_fields":{}}}}}}}},"422":{"description":"Invalid claim_condition_type"}}}},"/v1/admin/promotions/{id}":{"get":{"tags":["Promotion (Admin)"],"summary":"Get promotion by ID","description":"Retrieve a single promotion by its ID with its category.","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"description":"Promotion ID (ULID)","schema":{"type":"string"},"example":"01HXY..."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"id":"01HXY...","title":"Welcome Bonus 100%","description":"Get 100% bonus on your first deposit","terms_conditions":"Minimum deposit 100. Max bonus 5000.","bonus_type":1,"bonus_value":100,"max_payout":5000,"max_withdrawal":50,"claim_condition_type":1,"claim_conditions":{"min_deposit":100},"start_date":"2026-01-01T00:00:00+08:00","end_date":"2026-04-01T00:00:00+08:00","turnover":20,"winover":0,"turnover_type":1,"provider_category_ids":[1,3,5],"banner_image_url":"promotions/abc123.png","promo_image_url":"promotions/xyz789.png","status":1,"sort_order":0,"promotion_category_id":"01HXY...","display_type":1,"is_clearable":false,"created_by":"admin-user-id","created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T00:00:00+08:00","category":{"id":"01HXY...","name":"Welcome Bonus"}}}}}},"404":{"description":"Promotion not found"}}},"put":{"tags":["Promotion (Admin)"],"summary":"Update promotion","description":"Update an existing promotion. Only provided fields are updated (partial update).\nSupports file upload for banner and promo images via multipart/form-data.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"description":"Promotion ID (ULID)","schema":{"type":"string"},"example":"01HXY..."}],"requestBody":{"required":true,"description":"Fields to update (only provided values are applied)","content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UpdatePromotionRequest"}}}},"responses":{"200":{"description":"Promotion updated successfully"},"404":{"description":"Promotion not found"},"422":{"description":"Validation failed"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"delete":{"tags":["Promotion (Admin)"],"summary":"Delete promotion","description":"Soft-delete a promotion by ID. Also cleans up R2 images.","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"description":"Promotion ID (ULID)","schema":{"type":"string"},"example":"01HXY..."}],"responses":{"200":{"description":"Promotion deleted successfully","content":{"application/json":{"example":{"status":true,"message":"Promotion deleted.","data":null}}}},"404":{"description":"Promotion not found"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/admin/user-promotions":{"get":{"tags":["Promotion (Admin)"],"summary":"List player promotion records","description":"Paginated list of player promotion claim records with filters.\nAdmin authentication required.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"user_id","in":"query","description":"Filter by user ID (optional)","schema":{"type":"string"}},{"name":"user_name","in":"query","description":"Filter by player name (optional, partial match)","schema":{"type":"string"}},{"name":"promotion_id","in":"query","description":"Filter by promotion ID (optional)","schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by status (optional)","schema":{"type":"integer"}},{"name":"date_from","in":"query","description":"Filter records from this date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"date_to","in":"query","description":"Filter records until this date (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"per_page","in":"query","description":"Items per page (default 15)","schema":{"type":"integer","default":15}},{"name":"page","in":"query","description":"Page number","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful paginated response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":"01HXY...","promotion_id":"01HXY...","promotion_title":"Welcome Bonus 100%","user_id":"01HXY...","user_name":"player123","target_turnover":4000,"current_turnover":1500.5,"bonus_amount":100,"max_withdrawal":5000,"status":1,"is_clearable":false,"claimed_at":"2026-02-26T00:00:00+08:00","completed_at":null,"created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T20:00:00+08:00"}],"meta":{"pagination":{"total":12,"per_page":15,"current_page":1,"last_page":1,"from":1,"to":12,"has_more":false}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/admin/user-promotions/export":{"get":{"tags":["Promotion (Admin)"],"summary":"Export player promotion records","description":"Export player promotion claim records (same filters as list, no pagination).\nReturns full records as JSON array.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"user_id","in":"query","schema":{"type":"string"}},{"name":"user_name","in":"query","schema":{"type":"string"}},{"name":"promotion_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"integer"}},{"name":"date_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"date_to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"All matching records returned as JSON array","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":"01HXY...","promotion_id":"01HXY...","promotion_title":"Welcome Bonus 100%","user_id":"01HXY...","user_name":"player123","target_turnover":4000,"current_turnover":1500.5,"bonus_amount":100,"max_withdrawal":5000,"status":1,"claimed_at":"2026-02-26T00:00:00+08:00"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/admin/user-promotions/{id}/forfeit":{"post":{"tags":["Promotion (Admin)"],"summary":"Forfeit a player promotion record","description":"Forfeit a specific player promotion record by ID.\nClears bonus balance and marks the record as forfeited.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"description":"UserPromotion record ID (ULID)","schema":{"type":"string"}}],"responses":{"200":{"description":"Promotion forfeited","content":{"application/json":{"example":{"status":true,"message":"Promotion forfeited.","data":null}}}},"422":{"description":"Forfeit failed (e.g. not in progress)"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/admin/users/{userId}/promotions/forfeit":{"post":{"tags":["Promotion (Admin)"],"summary":"Forfeit all promotions for a user","description":"Forfeit all in-progress promotions for a specific user.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"userId","in":"path","required":true,"description":"User ID (ULID)","schema":{"type":"string"}}],"responses":{"200":{"description":"All user promotions forfeited","content":{"application/json":{"example":{"status":true,"message":"User promotions forfeited.","data":{"forfeited_count":2}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/admin/promotion-categories":{"get":{"tags":["Promotion Category (Admin)"],"summary":"List promotion categories (admin)","description":"Paginated list of promotion categories with search and status filter.\nAdmin authentication required.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"search","in":"query","description":"Search by category name (optional)","schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by status: 0=inactive, 1=active (optional)","schema":{"type":"integer","enum":[0,1]}},{"name":"per_page","in":"query","description":"Items per page (default 15)","schema":{"type":"integer","default":15}},{"name":"page","in":"query","description":"Page number","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful paginated response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":"01HXY...","name":"Welcome Bonus","description":"Welcome bonus promotions for new players","sort_order":0,"banner_url":"https://cdn.example.com/category-banner.png","status":1,"created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T00:00:00+08:00"}],"meta":{"pagination":{"total":2,"per_page":15,"current_page":1,"last_page":1,"from":1,"to":2,"has_more":false}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Promotion Category (Admin)"],"summary":"Create promotion category","description":"Create a new promotion category. Admin authentication required.","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePromotionCategoryRequest"},"example":{"name":"Welcome Bonus","description":"Welcome bonus promotions for new players","sort_order":0,"banner_url":"https://cdn.example.com/category-banner.png","status":1}}}},"responses":{"201":{"description":"Promotion category created"},"422":{"description":"Validation failed"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/admin/promotion-categories/{id}":{"get":{"tags":["Promotion Category (Admin)"],"summary":"Get promotion category by ID","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"description":"Promotion category ID (ULID)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"id":"01HXY...","name":"Welcome Bonus","description":"Welcome bonus promotions for new players","sort_order":0,"banner_url":"https://cdn.example.com/category-banner.png","status":1,"created_at":"2026-02-26T00:00:00+08:00","updated_at":"2026-02-26T00:00:00+08:00"}}}}},"404":{"description":"Promotion category not found"}}},"put":{"tags":["Promotion Category (Admin)"],"summary":"Update promotion category","description":"Only provided fields are updated (partial update).","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePromotionCategoryRequest"},"example":{"name":"Hot Promotion","sort_order":1}}}},"responses":{"200":{"description":"Promotion category updated"},"404":{"description":"Promotion category not found"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"delete":{"tags":["Promotion Category (Admin)"],"summary":"Delete promotion category","description":"Soft-delete a promotion category by ID.","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Promotion category deleted","content":{"application/json":{"example":{"status":true,"message":"Promotion category deleted.","data":null}}}},"404":{"description":"Promotion category not found"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/admin/provider-credentials/providers":{"get":{"tags":["Provider Credential (Admin)"],"summary":"List providers with credential info","description":"Returns all providers with their credential schema, categories, and configuration status.\nOptionally filter by provider_id to get a single provider.\nProxied to the Go game service via gRPC.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"provider_id","in":"query","required":false,"schema":{"type":"integer","format":"int64"},"description":"Optional provider ID to filter for a single provider","example":1}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"items":[{"providerId":1,"providerCode":"JILI","providerName":"JILI","credentialFields":[{"key":"agent_id","label":"Agent ID","type":"text","required":true},{"key":"agent_key","label":"Agent Key","type":"secret","required":true}],"providerCategories":[{"id":1,"name":"JILI - SLOTS","status":true}],"hasCredentials":false,"status":false}]}}}}},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/provider-credentials":{"post":{"tags":["Provider Credential (Admin)"],"summary":"Save provider credentials","description":"Create or update (upsert) encrypted credentials for a provider.\nValidates against the provider's credential_schema, encrypts values, and auto-runs a connection test.\nProxied to the Go game service via gRPC.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveProviderCredentialRequest"},"example":{"provider_id":1,"api_url":"https://api.jili.com/v1","credential_fields":"{\"agent_id\":\"AG123\",\"agent_key\":\"secret-key-here\"}","status":true,"env":"staging","kiosk_url":"","kiosk_username":"","kiosk_password":"","remark":"","provider_categories":[{"category_id":1,"status":true},{"category_id":2,"status":false}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"success":true,"isValid":true,"message":"Credentials saved and connection verified"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/provider-credentials/status/{providerId}":{"get":{"tags":["Provider Credential (Admin)"],"summary":"Get credential configuration status","description":"Returns credential configuration status (no credential values).\n- With `providerId`: returns status for that provider.\n- Without `providerId` (`/status`): returns status for all configured providers.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"providerId","in":"path","required":false,"schema":{"type":"integer","format":"int64"},"description":"Provider ID (optional, omit to get all)","example":1},{"name":"status","in":"query","required":false,"schema":{"type":"boolean"},"description":"Filter: true=active, false=inactive, omit=all"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"items":[{"providerId":1,"providerCode":"JILI","providerName":"JILI","configured":true,"apiUrl":"https://api.jili.com/v1","status":true,"isValid":true,"isWhitelist":false,"needTopup":false,"env":"staging","hasKioskPassword":false,"remark":"","updatedAt":"2026-03-16T12:00:00+08:00","verifiedAt":"2026-03-16T12:00:00+08:00","fieldKeys":["agent_id","agent_key"]}]}}}}},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/provider-credentials/test-connection":{"post":{"tags":["Provider Credential (Admin)"],"summary":"Test provider connection","description":"Decrypts stored credentials and runs a live connection test against the provider.\nUpdates `is_valid` and `verified_at` based on the result.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider_id"],"properties":{"provider_id":{"type":"integer","format":"int64","example":1}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"success":true,"message":"Connected successfully","latencyMs":142}}}}},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/provider-credentials/values/{providerId}":{"get":{"tags":["Provider Credential (Admin)"],"summary":"Get decrypted credential values","description":"Returns decrypted credential values with secret fields masked (e.g. `******22f0`).\n- With `providerId`: returns values for that provider.\n- Without `providerId` (`/values`): returns values for all configured providers.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"providerId","in":"path","required":false,"schema":{"type":"integer","format":"int64"},"description":"Provider ID (optional, omit to get all)","example":1},{"name":"status","in":"query","required":false,"schema":{"type":"boolean"},"description":"Filter: true=active, false=inactive, omit=all"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"items":[{"providerId":1,"providerCode":"JILI","providerName":"JILI","apiUrl":"https://api.jili.com/v1","credentialFields":{"agent_id":"AG123","agent_key":"******here"},"status":true,"isValid":true,"isWhitelist":false,"needTopup":false,"env":"staging","kioskUrl":"","kioskUsername":"","kioskPassword":"","remark":"","verifiedAt":"2026-03-16T12:00:00+08:00","providerCategories":[{"id":1,"name":"JILI - SLOTS","status":true}]}]}}}}},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/provider-categories/{categoryId}/status":{"put":{"tags":["Provider Credential (Admin)"],"summary":"Enable or disable a provider category","description":"Toggle the status of a provider category (enable/disable).","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"categoryId","in":"path","required":true,"schema":{"type":"integer","format":"int64"},"description":"Provider category ID","example":1}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"boolean","description":"Enable (true) or disable (false)","example":true}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"success":true,"message":"Category enabled"}}}}},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/service-categories":{"get":{"tags":["Catalog"],"summary":"List service categories (admin)","description":"Retrieve all service categories with resolved icon URLs. Admin authentication required.\nReturns every row regardless of status or maintenance window — admin always opts out\nof the active-cascade by sending `include_inactive=true` to the gRPC layer.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":1,"name":"Sports / E-sports","slug":"sports-esports","iconUrl":"","activeIconUrl":"","status":true,"maintenance":false,"maintenanceStartAt":"","maintenanceEndAt":"","sortOrder":0}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/service-categories/reorder":{"post":{"tags":["Catalog"],"summary":"Bulk reorder service categories","description":"Assigns dense `sort_order = 1..M` across the whole table. Listed IDs take\npositions 1..len(listed) in the order given; any rows not in the list are\nappended in their current relative order. Non-existent IDs are silently skipped.\nAfter the call, sort_order values are guaranteed dense (no gaps, no duplicates).\n`updated` in the response is the count of listed IDs that actually existed.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ordered_ids"],"properties":{"ordered_ids":{"type":"array","items":{"type":"integer","format":"int64","minimum":1},"minItems":1,"description":"Service category IDs in desired display order."}}},"example":{"ordered_ids":[3,1,2]}}}},"responses":{"200":{"description":"Reordered","content":{"application/json":{"example":{"status":true,"message":null,"data":{"success":true,"message":"reordered","updated":3}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Validation failed"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/service-categories/{serviceCategoryId}":{"post":{"tags":["Catalog"],"summary":"Update service category icon and maintenance","description":"Update icon, active icon, and/or maintenance fields on a service category.\nIcon files are uploaded to R2. Uses POST (not PUT) to support multipart file upload.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"serviceCategoryId","in":"path","required":true,"schema":{"type":"integer","format":"int64"},"description":"Service category ID","example":1}],"requestBody":{"required":false,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"icon":{"type":"string","format":"binary","description":"Icon image file (png, jpg, jpeg, svg, webp; max 5MB)"},"active_icon":{"type":"string","format":"binary","description":"Active icon image file (png, jpg, jpeg, svg, webp; max 5MB)"},"maintenance":{"type":"boolean","example":false},"maintenance_start_at":{"type":"string","format":"date-time","nullable":true},"maintenance_end_at":{"type":"string","format":"date-time","nullable":true,"description":"Must be >= maintenance_start_at"},"sort_order":{"type":"integer","minimum":0,"description":"Move this row to position N (1-indexed). The row is spliced into the\nrequested slot and other rows shift to make room. After the call, the\nwhole table is renumbered to dense 1..M (no gaps, no duplicates).\nPosition is clamped to [1, table_size]. **0 or omitted = no change.**\n","example":1},"status":{"type":"boolean","description":"Active flag — toggles category visibility in user-facing lists.","example":true}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"success":true,"message":"Service category updated","previousIconUrl":"acme/service-categories/abc123.webp","previousActiveIconUrl":"acme/service-categories/def456.webp"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Service category not found"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/provider-categories":{"get":{"tags":["Catalog"],"summary":"List provider categories (admin)","description":"Retrieve provider categories with resolved icon URLs. Optional provider_id filter.\nReturns every row regardless of status or maintenance window — admin opts out of\nthe active-cascade.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"provider_id","in":"query","description":"Filter by provider ID (optional)","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":1,"name":"JILI - SLOTS","providerId":1,"serviceCategoryId":3,"categoryName":"Slots","status":true,"iconUrl":"","walletType":1,"maintenance":false,"maintenanceStartAt":"","maintenanceEndAt":"","sortOrder":0},{"id":100,"name":"lobbykiss","providerId":500003,"serviceCategoryId":9,"categoryName":"Casino App","status":true,"iconUrl":"","walletType":3,"maintenance":false,"maintenanceStartAt":"","maintenanceEndAt":"","sortOrder":1}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/provider-categories/reorder":{"post":{"tags":["Catalog"],"summary":"Bulk reorder provider categories","description":"Assigns dense `sort_order = 1..M` across the whole table. Listed IDs take\npositions 1..len(listed) in the order given; any rows not in the list are\nappended in their current relative order. Non-existent IDs are silently skipped.\nAfter the call, sort_order values are guaranteed dense (no gaps, no duplicates).\n`updated` in the response is the count of listed IDs that actually existed.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ordered_ids"],"properties":{"ordered_ids":{"type":"array","items":{"type":"integer","format":"int64","minimum":1},"minItems":1,"description":"Provider category IDs in desired display order."}}},"example":{"ordered_ids":[42,17,9,3]}}}},"responses":{"200":{"description":"Reordered","content":{"application/json":{"example":{"status":true,"message":null,"data":{"success":true,"message":"reordered","updated":4}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Validation failed"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/provider-categories/{providerCategoryId}":{"post":{"tags":["Catalog"],"summary":"Update provider category icon and maintenance","description":"Update icon and/or maintenance fields on a provider category.\nIcon file is uploaded to R2. Uses POST (not PUT) to support multipart file upload.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"providerCategoryId","in":"path","required":true,"schema":{"type":"integer","format":"int64"},"description":"Provider category ID","example":1}],"requestBody":{"required":false,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"icon":{"type":"string","format":"binary","description":"Icon image file (png, jpg, jpeg, svg, webp; max 5MB)"},"maintenance":{"type":"boolean","example":false},"maintenance_start_at":{"type":"string","format":"date-time","nullable":true},"maintenance_end_at":{"type":"string","format":"date-time","nullable":true,"description":"Must be >= maintenance_start_at"},"sort_order":{"type":"integer","minimum":0,"description":"Move this row to position N (1-indexed). The row is spliced into the\nrequested slot and other rows shift to make room. After the call, the\nwhole table is renumbered to dense 1..M (no gaps, no duplicates).\nPosition is clamped to [1, table_size]. **0 or omitted = no change.**\n","example":1}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"success":true,"message":"Provider category updated","previousIconUrl":"acme/provider-categories/abc123.webp"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Provider category not found"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/services":{"get":{"tags":["Catalog"],"summary":"List services (admin)","description":"Retrieve services with resolved icon URLs. Intended for admin pickers\n(e.g. selecting services to add into a custom category) and for the\nservices management table. All filters are optional. Admin always opts\nout of the parent + maintenance-window cascade, so disabled services\nand services with disabled providers / categories are returned. The\nexplicit `status` query param still narrows by `services.status`.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"provider_id","in":"query","description":"Filter by provider ID","schema":{"type":"integer","format":"int64"},"example":1},{"name":"category_id","in":"query","description":"Filter by service category ID","schema":{"type":"integer","format":"int64"},"example":3},{"name":"provider_category_ids","in":"query","description":"Filter by one or more provider category IDs","schema":{"type":"array","items":{"type":"integer","format":"int64"}},"example":[2,5]},{"name":"status","in":"query","description":"Filter by active status. Omit to include all.","schema":{"type":"boolean"},"example":true}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"total":2,"services":[{"id":18,"providerId":1,"providerName":"jili","name":{"en":"Royal Fishing"},"serviceCode":"1","categoryId":5,"categoryName":"Fishing","rtp":"96.50","iconUrl":"https://r2.example.com/services/royal-fishing.png","status":true,"serviceTag":1,"maintenance":false,"providerCategoryId":2,"sortOrder":0},{"id":19,"providerId":1,"providerName":"jili","name":{"en":"Money Coming"},"serviceCode":"2","categoryId":3,"categoryName":"Slots","iconUrl":"","status":false,"maintenance":false,"providerCategoryId":4,"sortOrder":1}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/services/reorder":{"post":{"tags":["Catalog"],"summary":"Bulk reorder services","description":"Assigns dense `sort_order = 1..M` across the whole table. Listed IDs take\npositions 1..len(listed) in the order given; any rows not in the list are\nappended in their current relative order. Non-existent IDs are silently skipped.\nAfter the call, sort_order values are guaranteed dense (no gaps, no duplicates).\n`updated` in the response is the count of listed IDs that actually existed.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ordered_ids"],"properties":{"ordered_ids":{"type":"array","items":{"type":"integer","format":"int64","minimum":1},"minItems":1,"description":"Service IDs in desired display order."}}},"example":{"ordered_ids":[18,19,25]}}}},"responses":{"200":{"description":"Reordered","content":{"application/json":{"example":{"status":true,"message":null,"data":{"success":true,"message":"reordered","updated":3}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Validation failed"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/services/{serviceId}":{"post":{"tags":["Catalog"],"summary":"Update service (status, tag, RTP, maintenance)","description":"Update editable fields on a single service. All body fields are optional;\nonly provided fields are persisted. Maintenance dates are cleared when\n`maintenance` is sent without explicit start/end. To clear `rtp`, send an\nempty string.\n\nUses POST (not PUT) for consistency with other admin update endpoints.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"serviceId","in":"path","required":true,"schema":{"type":"integer","format":"int64"},"description":"Service ID","example":18}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","description":"Active flag","example":true},"service_tag":{"type":"integer","enum":[0,1,2],"description":"0=none, 1=hot, 2=new","example":1},"rtp":{"type":"string","nullable":true,"description":"RTP as decimal string, 0–100. Empty string clears.","example":"96.50"},"maintenance":{"type":"boolean","example":false},"maintenance_start_at":{"type":"string","format":"date-time","nullable":true},"maintenance_end_at":{"type":"string","format":"date-time","nullable":true,"description":"Must be >= maintenance_start_at"},"sort_order":{"type":"integer","minimum":0,"description":"Move this row to position N (1-indexed). The row is spliced into the\nrequested slot and other rows shift to make room. After the call, the\nwhole table is renumbered to dense 1..M (no gaps, no duplicates).\nPosition is clamped to [1, table_size]. **0 or omitted = no change.**\n","example":1}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"success":true,"message":"Service updated"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Service not found"},"422":{"description":"Validation failed"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/custom-categories":{"get":{"tags":["Custom Category (Admin)"],"summary":"List custom categories","description":"Paginated list of custom categories with their items, ordered by sort_order.","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"search","in":"query","description":"Search by category name (optional)","schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by status (optional)","schema":{"type":"boolean"}},{"name":"per_page","in":"query","description":"Items per page (default 15)","schema":{"type":"integer","default":15}},{"name":"page","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Paginated list of custom categories","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":1,"name":"Hot Games","slug":"hot-games","icon_url":"https://r2.example.com/custom-categories/hot.png","active_icon_url":"https://r2.example.com/custom-categories/hot-active.png","sort_order":0,"status":true,"items":[{"id":1,"itemable_type":"provider","itemable_id":1,"sort_order":0,"itemable":{"id":1,"name":"JILI"}},{"id":2,"itemable_type":"service_category","itemable_id":3,"sort_order":1,"itemable":{"id":3,"name":"Slots"}},{"id":3,"itemable_type":"provider_category","itemable_id":12,"sort_order":2,"itemable":{"id":12,"name":"JILI Slots"}},{"id":4,"itemable_type":"service","itemable_id":101,"sort_order":3,"itemable":{"id":101,"name":"{\"en\":\"Fortune Tiger\"}"}}]}],"meta":{"pagination":{"total":1,"per_page":15,"current_page":1,"last_page":1,"from":1,"to":1,"has_more":false}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Custom Category (Admin)"],"summary":"Create custom category","description":"Create a new custom category with optional icon uploads. Sort order auto-increments if not provided.","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Display name (required, slug auto-generated from name)","example":"Hot Games"},"icon":{"type":"string","format":"binary","description":"Icon image (jpg, jpeg, png, webp, svg; max 5MB)"},"active_icon":{"type":"string","format":"binary","description":"Active icon image (jpg, jpeg, png, webp, svg; max 5MB)"},"sort_order":{"type":"integer","description":"Display ordering (auto-increments if omitted)"},"status":{"type":"boolean","description":"Active/inactive (default true)"}}}}}},"responses":{"201":{"description":"Custom category created"},"422":{"description":"Validation error"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/admin/custom-categories/{id}":{"get":{"tags":["Custom Category (Admin)"],"summary":"Get custom category","description":"Retrieve a single custom category with all its items.","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Successful response"},"404":{"description":"Custom category not found"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"put":{"tags":["Custom Category (Admin)"],"summary":"Update custom category","description":"Update custom category fields (name, icons, sort_order, status). Only provided fields are updated. Slug auto-regenerated from name.","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"example":1}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Casino Games"},"icon":{"type":"string","format":"binary"},"active_icon":{"type":"string","format":"binary"},"sort_order":{"type":"integer","example":2},"status":{"type":"boolean","example":false}}}}}},"responses":{"200":{"description":"Custom category updated"},"404":{"description":"Custom category not found"},"422":{"description":"Validation error"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"delete":{"tags":["Custom Category (Admin)"],"summary":"Delete custom category","description":"Delete a custom category and all its items (cascade). Cleans up R2 icons.","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Custom category deleted","content":{"application/json":{"example":{"status":true,"message":"Custom category deleted.","data":null}}}},"404":{"description":"Custom category not found"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/admin/custom-categories/{id}/items":{"post":{"tags":["Custom Category (Admin)"],"summary":"Add items to custom category","description":"Add one or more items to a custom category.\nType must be one of: `service_category`, `provider_category`, `service`.\nEach item is validated against the database. Duplicates are rejected.\nSort order auto-increments if not provided.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"example":1}],"requestBody":{"required":true,"content":{"application/json":{"example":{"items":[{"type":"service_category","id":3},{"type":"provider_category","id":12},{"type":"service","id":101,"sort_order":5}]}}}},"responses":{"200":{"description":"Items added — returns category with all items"},"404":{"description":"Custom category not found"},"422":{"description":"Invalid type, item not found, or duplicate item"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"put":{"tags":["Custom Category (Admin)"],"summary":"Bulk update items","description":"Bulk update item fields (currently sort_order) within a custom category.","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"example":1}],"requestBody":{"required":true,"content":{"application/json":{"example":{"items":[{"id":1,"sort_order":2},{"id":2,"sort_order":0},{"id":3,"sort_order":1}]}}}},"responses":{"200":{"description":"Items updated — returns category with all items"},"404":{"description":"Custom category not found"},"422":{"description":"Item not found"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/admin/custom-categories/{id}/items/{itemId}":{"delete":{"tags":["Custom Category (Admin)"],"summary":"Remove item from custom category","description":"Remove a single item. The item must belong to the specified category.","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Custom category ID","example":1},{"name":"itemId","in":"path","required":true,"schema":{"type":"integer"},"description":"Custom category item ID","example":3}],"responses":{"200":{"description":"Item removed","content":{"application/json":{"example":{"status":true,"message":"Item removed.","data":null}}}},"404":{"description":"Item not found or does not belong to category"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/admin/users/{userId}/provider-balances":{"get":{"tags":["Provider Balance (Admin)"],"summary":"List user provider balances","description":"Returns all (provider, aggregator) rows for a user from the snapshot table.\nReads only from `user_provider_balances` — no live provider API calls.\nEach row includes `balance_status: \"stale\"` (snapshot only; use refresh for live fetch).\nMissing rows (user never played that provider) render as `balance: \"0\"` and `last_synced_at: null`.\nProviders with sub-wallets (e.g. AP) appear as multiple rows: AP main + AP (CMDT) + AP (UGT).\nProxied to the Go game service via gRPC.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User ID","example":"01JTHZN1FDJMZ2B9GDMSA4THXY"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"rows":[{"provider_id":1,"provider_code":"ap","display_name":"AP","aggregator":"0","wallet_type":2,"is_seamless":false,"balance":"1500.000000","last_synced_at":"2026-05-14T10:00:00Z","provider_status":true,"maintenance":false,"balance_status":"stale"},{"provider_id":1,"provider_code":"ap","display_name":"AP (CMDT)","aggregator":"cmdt","wallet_type":2,"is_seamless":false,"balance":"200.000000","last_synced_at":"2026-05-14T10:00:00Z","provider_status":true,"maintenance":false,"balance_status":"stale"},{"provider_id":1,"provider_code":"ap","display_name":"AP (UGT)","aggregator":"ugt","wallet_type":2,"is_seamless":false,"balance":"0","last_synced_at":null,"provider_status":true,"maintenance":false,"balance_status":"stale"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/users/{userId}/provider-balances/refresh":{"post":{"tags":["Provider Balance (Admin)"],"summary":"Refresh user provider balances","description":"Fans out live `GetBalance` calls to every (provider, aggregator) where the user has a\n`service_tokens` row. Updates the `user_provider_balances` snapshot with fresh values.\nSeamless providers and providers with no `service_tokens` row are silently skipped.\nOn per-provider failure the row's `balance_status` is set to `\"failed\"` and the snapshot\nkeeps its previous value. Successfully refreshed rows have `balance_status: \"ok\"`.\nUp to 8 providers are queried concurrently. Sub-wallets within the same provider\n(e.g. AP cmdt/ugt) are queried sequentially to avoid provider-side deadlocks.\nAll provider API calls are traced in `provider_api_logs` with `user_id` for traceability.\nProxied to the Go game service via gRPC.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User ID","example":"01JTHZN1FDJMZ2B9GDMSA4THXY"}],"responses":{"200":{"description":"Successful response (partial failures are not errors — check `balance_status` on each row)","content":{"application/json":{"example":{"status":true,"message":null,"data":{"rows":[{"provider_id":1,"provider_code":"ap","display_name":"AP","aggregator":"0","wallet_type":2,"is_seamless":false,"balance":"1500.000000","last_synced_at":"2026-05-14T10:05:00Z","provider_status":true,"maintenance":false,"balance_status":"ok"},{"provider_id":1,"provider_code":"ap","display_name":"AP (UGT)","aggregator":"ugt","wallet_type":2,"is_seamless":false,"balance":"0","last_synced_at":"2026-05-14T09:00:00Z","provider_status":true,"maintenance":false,"balance_status":"failed"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/users/{userId}/provider-balances/withdraw":{"post":{"tags":["Provider Balance (Admin)"],"summary":"Withdraw user from active provider session","description":"Manually drains the user's currently-active provider session and credits the balance\nback to the user's main wallet. Wraps `RestoreBalanceService` under a per-user\nPostgres advisory lock to prevent concurrent calls.\nUse this when support needs to recover funds parked at a provider.\nAll provider API calls are traced in `provider_api_logs` with `user_id` for traceability.\n\n**`status` values:**\n| Value | Meaning |\n|---|---|\n| `ok` | Funds withdrawn and credited to wallet |\n| `no_active_session` | User has no active provider session |\n| `no_token` | User has no `service_tokens` row for the active session's provider |\n| `failed` | Provider API or internal error — see `error` field |\n\nProxied to the Go game service via gRPC.\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User ID","example":"01JTHZN1FDJMZ2B9GDMSA4THXY"}],"responses":{"200":{"description":"Successful response (all status values return 200 — check `status` field)","content":{"application/json":{"examples":{"ok":{"summary":"Funds withdrawn","value":{"status":true,"message":null,"data":{"withdrawn":"1500.000000","status":"ok","provider_code":"ap","aggregator":"cmdt","error":""}}},"no_active_session":{"summary":"No active session","value":{"status":true,"message":null,"data":{"withdrawn":"0","status":"no_active_session","provider_code":"","aggregator":"","error":""}}},"no_token":{"summary":"No service token","value":{"status":true,"message":null,"data":{"withdrawn":"0","status":"no_token","provider_code":"","aggregator":"","error":""}}},"failed":{"summary":"Provider error","value":{"status":true,"message":null,"data":{"withdrawn":"0","status":"failed","provider_code":"jili","aggregator":"0","error":"connection timeout"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/users/{userId}/service-tokens":{"get":{"tags":["Service Token (Admin)"],"summary":"List user provider accounts","description":"Returns the provider account credentials (username/password) registered for a user\nacross all providers. Each row corresponds to a `service_tokens` entry — i.e. a\nprovider account the user has been enrolled into.\n\nView-only. Proxied to the Go game service via gRPC (`AdminServiceTokenService.AdminListUserServiceTokens`).\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User ID","example":"01JTHZN1FDJMZ2B9GDMSA4THXY"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"rows":[{"provider_id":7,"provider_name":"JILI","user_id":"01JTHZN1FDJMZ2B9GDMSA4THXY","username":"player001","password":"s3cr3t","created_at":"2026-05-06T02:58:11.249845Z"},{"provider_id":9,"provider_name":"FUMA","user_id":"01JTHZN1FDJMZ2B9GDMSA4THXY","username":"player001","password":"abc123","created_at":"2026-05-07T05:29:15.024153Z"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/admin/users/{userId}/service-restrictions":{"get":{"tags":["Service Restriction (Admin)"],"summary":"List user service restrictions","description":"Returns the full provider catalog for the tenant with restriction state overlaid for the\ngiven user. Each provider has a `blocked_all` flag (true when the entire provider is blocked),\nand each nested provider category has a `blocked` flag (true when only that specific\ncategory is blocked).\n\n**Sparse storage model:** the underlying `user_service_restrictions` table only stores rows\nfor restrictions that exist. A NULL `provider_category_id` row blocks the whole provider;\na category-level row blocks just that category. New providers added to the catalog after\na block was applied automatically appear with `blocked_all: false`.\n\nWhen `blocked_all: true`, the nested `categories[*].blocked` fields are always `false` —\nthe block is implicit. The UI should render the provider as fully off and grey-out the\ncategory toggles.\n\nProxied to the Go game service via gRPC (`AdminUserServiceRestrictionService.GetUserServiceRestrictions`).\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"User ID","example":"01JTHZN1FDJMZ2B9GDMSA4THXY"},{"name":"username","in":"query","required":true,"schema":{"type":"string"},"description":"Player username (passed through to the Go service; echoed back in the response so the UI does not need a separate lookup)","example":"player001"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"user_id":"01JTHZN1FDJMZ2B9GDMSA4THXY","username":"player001","providers":[{"provider_id":7,"name":"JILI","blocked_all":true,"categories":[{"provider_category_id":100,"name":"JILI - SLOTS","service_category_id":3,"blocked":false},{"provider_category_id":101,"name":"JILI - FISHING","service_category_id":5,"blocked":false}]},{"provider_id":9,"name":"FUMA","blocked_all":false,"categories":[{"provider_category_id":200,"name":"FUMA - SLOTS","service_category_id":3,"blocked":true},{"provider_category_id":201,"name":"FUMA - CRASH","service_category_id":6,"blocked":false}]}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}},"post":{"tags":["Service Restriction (Admin)"],"summary":"Set user service restrictions (bulk, declarative)","description":"Replaces the user's restrictions with the supplied desired state. Mirrors the GET response\nshape — frontend sends back the same tree with toggled `blocked_all` / `blocked` flags and\nthe server figures out the diff:\n\n- Rows that already match the desired state are **left untouched** (their `created_at` and\n  `created_by` are preserved).\n- New blocks become inserts. Removed blocks become deletes.\n\nAll changes apply atomically in a single transaction. Idempotent: sending the same state\ntwice is a no-op.\n\n**Semantics per provider entry:**\n| Input | Persisted state |\n|---|---|\n| `blocked_all: true` (categories ignored) | One row with NULL `provider_category_id` — blocks every category under this provider |\n| `blocked_all: false` + categories with `blocked: true` | One row per blocked category |\n| `blocked_all: false` + no `blocked: true` categories | No rows (everything under this provider is allowed) |\n\n**Conflict rule:** A provider entry with `blocked_all: true` AND any category with\n`blocked: true` is rejected (`InvalidArgument`) — the caller must pick one.\n\nProxied to the Go game service via gRPC (`AdminUserServiceRestrictionService.SetUserServiceRestrictions`).\n","security":[{"AdminBearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XTenantId"},{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"example":"01JTHZN1FDJMZ2B9GDMSA4THXY"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["username","admin_username","providers"],"properties":{"username":{"type":"string","description":"Player username, snapshotted on each newly inserted row for admin display","example":"player001"},"admin_username":{"type":"string","description":"Acting admin's username — stored on each newly inserted row as `created_by`","example":"admin1"},"providers":{"type":"array","description":"Desired state per provider. Providers not in this list are unchanged — but the\ntypical FE flow is to send the full tree as returned by GET so the server can\nfully reconcile.\n","items":{"type":"object","required":["provider_id"],"properties":{"provider_id":{"type":"integer","format":"int64","example":7},"blocked_all":{"type":"boolean","description":"When true, the whole provider is blocked. `categories[*].blocked` must all be false.","example":false},"categories":{"type":"array","items":{"type":"object","required":["provider_category_id"],"properties":{"provider_category_id":{"type":"integer","format":"int64","example":200,"description":"provider category id from the catalog/list response."},"blocked":{"type":"boolean","example":true}}}}}}}}},"example":{"username":"player001","admin_username":"admin1","providers":[{"provider_id":7,"blocked_all":true,"categories":[]},{"provider_id":9,"blocked_all":false,"categories":[{"provider_category_id":200,"blocked":true},{"provider_category_id":201,"blocked":false}]}]}}}},"responses":{"200":{"description":"Successful response — diff applied","content":{"application/json":{"example":{"status":true,"message":null,"data":{"ok":true}}}}},"400":{"description":"Invalid payload. Common causes:\n* `username` or `admin_username` missing\n* a provider entry has `provider_id=0`\n* a provider entry has `blocked_all: true` AND a category with `blocked: true`\n* a category entry has `provider_category_id=0`\n"},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/central/service-categories":{"get":{"tags":["Game Provisioning (BO Central)"],"summary":"List service categories (central)","description":"Returns all service_categories rows from the game_central schema.\nNo tenant context required. Used by BO Central for reference dropdowns\n(e.g., associating sales rates with a service category).\n","security":[{"CentralBearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":1,"name":"Sportsbook"},{"id":2,"name":"Live Casino"},{"id":3,"name":"Slots"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/central/game-catalog/promotable":{"get":{"tags":["Game Provisioning (BO Central)"],"summary":"List promotable providers","description":"Returns all providers from `tenant_acme` with a flag indicating whether each one\nhas already been promoted into the central catalog. Already-promoted providers are\nstill shown so operators can re-promote to pick up newly crawled games.\n","security":[{"CentralBearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"provider_id":1,"code":"pussy888","name":"Pussy888","in_central":true,"last_promoted_at":"2026-05-26T10:00:00Z"},{"provider_id":2,"code":"mega888","name":"Mega888","in_central":false,"last_promoted_at":null}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/central/game-catalog/promote":{"post":{"tags":["Game Provisioning (BO Central)"],"summary":"Promote providers to central catalog","description":"Copies selected providers (and all their categories + services) from `tenant_acme`\ninto the `game_central` schema, making them available for per-tenant provisioning.\n\nIdempotent — re-promoting a provider updates existing rows with the latest data from `tenant_acme`.\nEach provider is promoted in its own transaction; a failure on one does not affect others.\n","security":[{"CentralBearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider_ids"],"properties":{"provider_ids":{"type":"array","items":{"type":"integer"},"minItems":1,"example":[1,2]}}}}}},"responses":{"200":{"description":"Successful response (per-provider result)","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"provider_id":1,"success":true,"error_reason":null,"categories_promoted":3,"services_promoted":120},{"provider_id":99,"success":false,"error_reason":"not found in tenant_acme","categories_promoted":0,"services_promoted":0}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/central/game-catalog":{"get":{"tags":["Game Provisioning (BO Central)"],"summary":"List central catalog","description":"Returns the full central catalog (providers → categories → services).\n\nEach category carries `aggregator` (brand key — a brand is the `(provider_id, aggregator)`\ntuple, so one provider can hold several brands), `slug` (SEO brand slug, may be empty),\n`is_iframe` (tri-state: `null` = untested, `true` = embeds, `false` = blocked), and\n`is_disabled` (hard kill switch).\n\nPass `tenant_id` to get `tenant_provisioned` flags on each provider and category,\nindicating whether that tenant already has the item. Use this before provisioning\nto preview what will be new vs already exists.\n","security":[{"CentralBearerAuth":[]}],"parameters":[{"name":"provider_id","in":"query","schema":{"type":"integer"},"description":"Filter to a single provider (0 = no filter)"},{"name":"category_id","in":"query","schema":{"type":"integer"},"description":"Filter to a single category (0 = no filter)"},{"name":"active_only","in":"query","schema":{"type":"boolean"},"description":"Only return active providers/categories/services"},{"name":"tenant_id","in":"query","schema":{"type":"string"},"description":"When provided, each provider and category includes tenant_provisioned flag","example":"acme_test"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":7,"code":"tw_theone_agg","name":"THEONE","status":true,"tenant_provisioned":true,"categories":[{"id":123,"name":"PRAGMATIC PLAY - SLOTS","aggregator":"5","slug":"pp","is_iframe":true,"service_category_id":3,"status":true,"is_disabled":false,"tenant_provisioned":true,"services":[{"id":1001,"name":"Gates of Olympus","service_code":"vs20olympgate","status":true,"is_disabled":false}]},{"id":124,"name":"PRAGMATIC PLAY - LIVE","aggregator":"5","slug":"pp","is_iframe":true,"service_category_id":2,"status":true,"is_disabled":false,"tenant_provisioned":true,"services":[]}]}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/central/game-catalog/disable":{"post":{"tags":["Game Provisioning (BO Central)"],"summary":"Disable/enable a catalog entity (cluster-wide)","description":"Sets the `is_disabled` hard kill switch on a single `game_central` service or\nprovider_category and cascades the same value to that entity in every tenant database.\nTwo-way — `is_disabled: false` re-enables. Cluster-wide: no tenant in the path; the game\nservice enumerates tenants itself and returns per-tenant outcomes.\n","security":[{"CentralBearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entity_type","entity_id","is_disabled"],"properties":{"entity_type":{"type":"string","enum":["service","provider_category"],"example":"provider_category"},"entity_id":{"type":"integer","description":"game_central row id (services.id or provider_categories.id)","example":123},"is_disabled":{"type":"boolean","example":true}}}}}},"responses":{"200":{"description":"Cluster-wide result with per-tenant outcomes","content":{"application/json":{"example":{"status":true,"message":null,"data":{"central_rows_affected":1,"tenants_total":2,"tenants_succeeded":2,"tenants_failed":0,"tenant_results":[{"tenant_id":"acme","rows_affected":1,"error":null},{"tenant_id":"haaland","rows_affected":1,"error":null}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/central/game-catalog/brand-slug":{"post":{"tags":["Game Provisioning (BO Central)"],"summary":"Set a brand's SEO slug (cluster-wide)","description":"Sets the SEO `slug` on every provider_category row of a brand — identified by the\n`(provider_id, aggregator)` tuple — in `game_central`, and cascades it to every tenant\ndatabase. A \"brand\" is `(provider_id, aggregator)`: PRAGMATIC PLAY and JILI under the same\naggregator provider are distinct brands, each with its own slug.\n\n- `slug` may be empty → the server defaults it to a slugified brand label (e.g. `pragmatic-play`).\n- Format `^[a-z0-9-]+$`, max 30, strict — no auto-normalisation of spaces/uppercase.\n- Unique **per provider**: two brands under the same `provider_id` cannot share a slug\n  (422); a different provider may reuse it.\n\nCluster-wide: no tenant in the path; the game service enumerates tenants itself.\n","security":[{"CentralBearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider_id","aggregator"],"properties":{"provider_id":{"type":"integer","example":7},"aggregator":{"type":"string","description":"Brand key together with provider_id. Opaque string (may be \"0\").","example":"5"},"slug":{"type":"string","maxLength":30,"pattern":"^[a-z0-9-]+$","nullable":true,"description":"Empty → server derives it from the brand name.","example":"pp"}}}}}},"responses":{"200":{"description":"Effective slug written (the value actually persisted)","content":{"application/json":{"example":{"status":true,"message":null,"data":{"slug":"pp"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Invalid slug format, or slug already in use under this provider","content":{"application/json":{"example":{"status":false,"message":"Validation failed.","code":"VALIDATION_ERROR","errors":{"slug":["This slug is already in use for this provider."]}}}}},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/central/game-catalog/brand-iframe":{"post":{"tags":["Game Provisioning (BO Central)"],"summary":"Set a brand's iframe flag (cluster-wide)","description":"Sets `is_iframe` on every provider_category row of a brand — identified by\n`(provider_id, aggregator)` — in `game_central`, and cascades it to every tenant database.\nWrites a concrete `true`/`false`; the `null` \"untested\" state is only produced by the\niframe crawler, never here.\n\nCluster-wide: no tenant in the path; the game service enumerates tenants itself.\n","security":[{"CentralBearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider_id","aggregator","iframe"],"properties":{"provider_id":{"type":"integer","example":7},"aggregator":{"type":"string","example":"5"},"iframe":{"type":"boolean","example":true}}}}}},"responses":{"200":{"description":"Effective value written","content":{"application/json":{"example":{"status":true,"message":null,"data":{"iframe":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/central/tenants":{"post":{"tags":["Game Provisioning (BO Central)"],"summary":"Create tenant","description":"Creates a new tenant (Laravel DB + stancl migration) and immediately triggers a game\nservice migration to set up the tenant's schema in `game_db`.\n\nThe response always returns `201` even if the game migration fails — Laravel tenant\ncreation is independent of the game service. Check `game_migration.ok` to determine\nwhether the game schema was created. If `ok` is false, use\n`POST /v1/central/tenants/{tenantId}/game-migrate` to retry.\n","security":[{"CentralBearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","name","domain","admin_name","admin_email","admin_password"],"properties":{"id":{"type":"string","example":"acme_test"},"name":{"type":"string","example":"Acme Test"},"domain":{"type":"string","example":"acme-test.0wallet.com"},"admin_name":{"type":"string","example":"Super Admin"},"admin_email":{"type":"string","example":"admin@acme-test.com"},"admin_password":{"type":"string","example":"secret123"}}}}}},"responses":{"201":{"description":"Tenant created (game migration result included regardless of outcome)","content":{"application/json":{"example":{"status":true,"message":"Tenant created.","data":{"tenant":{"id":"acme_test","name":"Acme Test","status":1,"domains":[{"domain":"acme-test.0wallet.com"}],"created_at":"2026-05-26T10:00:00Z"},"game_migration":{"ok":true,"error":null}}}}}},"422":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/central/tenants/{tenantId}/game-provisions":{"get":{"tags":["Game Provisioning (BO Central)"],"summary":"List provisioning history","description":"Paginated audit log of all provisioning actions performed on this tenant, newest first.","security":[{"CentralBearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"},"example":"acme_test"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":"01JWFAKE000000000000000001","tenant_id":"acme_test","provider_ids":[1],"provider_category_ids":[10,11],"provisioned_by":"01HADMIN000000000000000001","provisioned_by_name":"Alice","result_summary":{"total_inserted":57,"total_skipped":0},"created_at":"2026-05-26T10:00:00Z"}],"meta":{"current_page":1,"last_page":1,"per_page":20,"total":1}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Game Provisioning (BO Central)"],"summary":"Provision providers to tenant","description":"Copies selected providers and categories from the central catalog into the target\ntenant's database, making those games available for that tenant's players.\n\nIdempotent — rows that already exist in the tenant are skipped (`total_skipped` reflects this).\nSafe to run multiple times. Each attempt is recorded in the provisioning audit log.\n","security":[{"CentralBearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"},"example":"acme_test"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider_ids","provider_category_ids"],"properties":{"provider_ids":{"type":"array","items":{"type":"integer"},"minItems":1,"example":[1]},"provider_category_ids":{"type":"array","items":{"type":"integer"},"minItems":1,"example":[10,11]}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":{"total_inserted":57,"total_skipped":0}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/ValidationError"},"502":{"$ref":"#/components/responses/GatewayError"}}}},"/v1/central/tenants/{tenantId}/game-migrate":{"post":{"tags":["Game Provisioning (BO Central)"],"summary":"Trigger game DB migration for tenant","description":"Creates and migrates the game service schema (`game_db`) for the specified tenant.\n\nCalled automatically when a tenant is created via `POST /v1/central/tenants`. Use this\nendpoint to retry the migration if the initial attempt failed (e.g., game service was\ntemporarily unavailable at creation time).\n\nIdempotent — safe to run on an already-migrated tenant. All migration steps check for\nexisting state before applying changes.\n","security":[{"CentralBearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"},"example":"acme_test"}],"responses":{"200":{"description":"Migration completed successfully","content":{"application/json":{"example":{"status":true,"message":"Game migration completed successfully.","data":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"description":"Game service migration failed","content":{"application/json":{"example":{"status":false,"message":"Game migration failed: rpc error: code = Internal desc = ...","data":null}}}}}}},"/v1/central/sales-rates":{"get":{"tags":["Sales Rate (BO Central)"],"summary":"List sales rate defaults","description":"Platform-wide master rate sheet — one row per `(provider_id, provider_category_id)`.\nThese defaults apply to every tenant unless a per-tenant override exists.\nPaginated (50 per page), ordered by provider then provider_category.\n","security":[{"CentralBearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":"01JABCXYZ...","provider_id":5,"provider_category_id":11,"rate":"6.00","status":true}],"meta":{"pagination":{"total":1,"per_page":50,"current_page":1,"last_page":1}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Sales Rate (BO Central)"],"summary":"Create a sales rate default","description":"Create a master default rate for a provider_category. `provider_category_id` is unique —\ncreating a second default for the same category returns 422.\nIDs come from the central catalog (`GET /v1/central/game-catalog`).\n","security":[{"CentralBearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider_id","provider_category_id","rate"],"properties":{"provider_id":{"type":"integer","example":5},"provider_category_id":{"type":"integer","example":11},"rate":{"type":"number","format":"float","minimum":0,"maximum":100,"example":6.0},"status":{"type":"boolean","example":true}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"example":{"status":true,"message":"Resource created.","data":{"id":"01JABCXYZ...","provider_id":5,"provider_category_id":11,"rate":"6.00","status":true,"created_by":"01JADMIN..."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Validation error (e.g. duplicate provider_category_id)"}}}},"/v1/central/sales-rates/{id}":{"put":{"tags":["Sales Rate (BO Central)"],"summary":"Update a sales rate default","security":[{"CentralBearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Sales rate default ULID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rate":{"type":"number","format":"float","minimum":0,"maximum":100,"example":6.5},"status":{"type":"boolean","example":true}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"example":{"status":true,"message":null,"data":{"id":"01JABCXYZ...","provider_id":5,"provider_category_id":11,"rate":"6.50","status":true,"updated_by":"01JADMIN..."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found"},"422":{"description":"Validation error"}}},"delete":{"tags":["Sales Rate (BO Central)"],"summary":"Delete a sales rate default","security":[{"CentralBearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Sales rate default ULID"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"example":{"status":true,"message":"Sales rate default deleted.","data":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found"}}}},"/v1/central/sales-rate-snapshots":{"get":{"tags":["Sales Rate (BO Central)"],"summary":"List daily kiosk snapshots","description":"Read-only cross-tenant report. One row per `(snapshot_date, tenant, provider_category)`\nwith pre-computed money figures. `kiosk_amount = (total_bet_amount − total_payout_amount) × rate / 100`.\nRows with no defined rate are still written with `rate`/`kiosk_amount` null and `source: \"missing\"`\nso reports can spot gaps. Paginated (100 per page).\n","security":[{"CentralBearerAuth":[]}],"parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date"},"example":"2026-05-01"},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date"},"example":"2026-05-20"},{"name":"tenant_id","in":"query","schema":{"type":"string"},"description":"Filter to one tenant","example":"acme"},{"name":"service_category_id","in":"query","schema":{"type":"integer"},"description":"Filter by service category (e.g. all Slots)"},{"name":"provider_id","in":"query","schema":{"type":"integer"}},{"name":"provider_category_id","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":"01JSNAP...","snapshot_date":"2026-05-20","tenant_id":"acme","provider_id":5,"provider_category_id":11,"service_category_id":1,"total_bet_amount":"1500000.0000","total_valid_turnover":"1430000.0000","total_payout_amount":"1400000.0000","total_win_loss":"-100000.0000","rate":"6.00","kiosk_amount":"6000.0000","source":"default"},{"id":"01JSNAP2...","snapshot_date":"2026-05-20","tenant_id":"acme","provider_id":9,"provider_category_id":99,"service_category_id":1,"total_bet_amount":"50000.0000","total_valid_turnover":"48000.0000","total_payout_amount":"45000.0000","total_win_loss":"-5000.0000","rate":null,"kiosk_amount":null,"source":"missing"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Validation error (e.g. to before from)"}}}},"/v1/central/tenant-daily-totals":{"get":{"tags":["Sales Rate (BO Central)"],"summary":"List per-tenant daily total IN/OUT","description":"Read-only cross-tenant report. One row per `(summary_date, tenant)` rolled up across all\nprovider_categories. `total_in = SUM(total_bet_amount)`, `total_out = SUM(total_payout_amount)`.\nPromotion transactions are already included in the source game summaries. Paginated (100 per page).\n","security":[{"CentralBearerAuth":[]}],"parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date"},"example":"2026-05-01"},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date"},"example":"2026-05-20"},{"name":"tenant_id","in":"query","schema":{"type":"string"},"description":"Filter to one tenant","example":"acme"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":"01JTOTAL...","summary_date":"2026-05-20","tenant_id":"acme","total_in":"8350000.0000","total_out":"7815000.0000","total_win_loss":"-535000.0000"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Validation error (e.g. to before from)"}}}},"/v1/central/tenants/{tenantId}/sales-rate-overrides":{"get":{"tags":["Sales Rate (BO Central)"],"summary":"List sales rate overrides for a tenant","description":"Per-tenant negotiated rates that beat the central default at resolve time.\nCentral-only — admin guard has no access. Paginated (50 per page).\n","security":[{"CentralBearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"},"example":"acme"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":true,"message":null,"data":[{"id":"01JOVR...","provider_category_id":11,"rate":"11.00","status":true}],"meta":{"pagination":{"current_page":1,"last_page":1,"per_page":50,"total":1}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Tenant not found"}}}},"/v1/central/tenants/{tenantId}/sales-rate-overrides/{providerCategoryId}":{"put":{"tags":["Sales Rate (BO Central)"],"summary":"Upsert a sales rate override for a tenant","description":"Create or update a tenant's override for a provider_category. Restores a\npreviously soft-deleted override. The resolver prefers an active override over the\ncentral default.\n","security":[{"CentralBearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"},"example":"acme"},{"name":"providerCategoryId","in":"path","required":true,"schema":{"type":"integer"},"example":11}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rate"],"properties":{"rate":{"type":"number","format":"float","minimum":0,"maximum":100,"example":11.0},"status":{"type":"boolean","example":true}}}}}},"responses":{"200":{"description":"Upserted","content":{"application/json":{"example":{"status":true,"message":null,"data":{"id":"01JOVR...","provider_category_id":11,"rate":"11.00","status":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Tenant not found"},"422":{"description":"Validation error"}}},"delete":{"tags":["Sales Rate (BO Central)"],"summary":"Remove a sales rate override for a tenant","description":"Soft-deletes the tenant's override so the resolver falls back to the central\ndefault. The audit trail survives.\n","security":[{"CentralBearerAuth":[]}],"parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"},"example":"acme"},{"name":"providerCategoryId","in":"path","required":true,"schema":{"type":"integer"},"example":11}],"responses":{"200":{"description":"Removed","content":{"application/json":{"example":{"status":true,"message":"Override removed; resolver will fall back to default.","data":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Tenant not found or override not found"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"User JWT token (auth:api guard)"},"AdminBearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Admin JWT token (auth:admin guard)"},"CentralBearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"BO Central JWT token (auth:central guard)"}},"parameters":{"XTenantId":{"name":"X-Tenant-Id","in":"header","required":true,"description":"Tenant identifier for multi-tenancy resolution","schema":{"type":"string"},"example":"acme"}},"responses":{"Unauthorized":{"description":"Unauthorized - JWT token missing or invalid","content":{"application/json":{"example":{"status":false,"message":"Unauthenticated.","code":"UNAUTHENTICATED"}}}},"BadRequest":{"description":"Bad request - invalid parameters","content":{"application/json":{"example":{"status":false,"message":"Validation failed.","code":"VALIDATION_ERROR"}}}},"ValidationError":{"description":"Validation failed - one or more fields did not pass validation (422)","content":{"application/json":{"example":{"status":false,"message":"Validation failed.","code":"VALIDATION_ERROR","errors":{"field":["The field is required."]}}}}},"GatewayError":{"description":"Game service unavailable or returned an error","content":{"application/json":{"example":{"status":false,"message":"Failed to fetch data: [14] no connection","code":null}}}}},"schemas":{"Envelope":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","nullable":true,"example":null},"data":{"type":"object"}}},"PaginatedEnvelope":{"type":"object","properties":{"status":{"type":"boolean","example":true},"message":{"type":"string","nullable":true,"example":null},"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of records","example":50},"per_page":{"type":"integer","description":"Items per page","example":15},"current_page":{"type":"integer","description":"Current page number","example":1},"last_page":{"type":"integer","description":"Last page number","example":4},"from":{"type":"integer","nullable":true,"description":"First item index on current page","example":1},"to":{"type":"integer","nullable":true,"description":"Last item index on current page","example":15},"has_more":{"type":"boolean","description":"Whether there are more pages","example":true}}},"EnvelopeServiceListResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"services":{"type":"array","items":{"$ref":"#/components/schemas/ServiceItem"}}}}}}]},"ServiceItem":{"type":"object","description":"Service item. Note: field names are camelCase when serialised from protobuf\n(e.g. `providerId`, `providerName`, `serviceCode`, `categoryId`, `categoryName`,\n`iconUrl`, `serviceTag`, `providerCategoryId`).\n","properties":{"id":{"type":"integer","example":18},"providerId":{"type":"integer","example":1},"providerName":{"type":"string","example":"jili"},"name":{"type":"string","example":"Royal Fishing"},"serviceCode":{"type":"string","example":"1"},"categoryId":{"type":"integer","example":5},"categoryName":{"type":"string","example":"Fishing"},"rtp":{"type":"string","nullable":true,"example":"96.5"},"iconUrl":{"type":"string","example":""},"status":{"type":"boolean","example":true},"serviceTag":{"type":"integer","nullable":true,"description":"0=none, 1=hot, 2=new","example":1},"maintenance":{"type":"boolean","example":false},"providerCategoryId":{"type":"integer","nullable":true,"example":1}}},"EnvelopeCategoriesResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/CategoryItem"}}}}}}]},"CategoryItem":{"type":"object","description":"Default service category. Custom categories share the top-level shape but add\n`is_custom: true`, may use `sort_order` (snake_case), and their `items` follow a\ndifferent schema (with `type` + `action` discriminators) — see the endpoint examples.\n","properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Live Casino"},"slug":{"type":"string","example":"live-casino"},"iconUrl":{"type":"string","example":""},"activeIconUrl":{"type":"string","example":""},"status":{"type":"boolean","example":true},"sortOrder":{"type":"integer","example":0},"items":{"type":"array","description":"Live provider_categories belonging to this service_category. Filtered by the\nsame active-cascade as the category list itself, so under the user-facing default\nthis array is always non-empty.\n","items":{"$ref":"#/components/schemas/ServiceCategoryItem"}}}},"ServiceCategoryItem":{"type":"object","description":"One live provider_category nested under a default service category in\n`GET /v1/user/service/categories`. Distinct from custom-category items\n(which carry `type` + `action`).\n","properties":{"providerCategoryId":{"type":"integer","format":"int64","example":6},"serviceCategoryId":{"type":"integer","format":"int64","example":2},"name":{"type":"string","example":"ONGAMING - LIVE CASINO"},"providerId":{"type":"integer","format":"int64","example":500003},"walletType":{"type":"integer","description":"1 = seamless, 2 = transfer, 3 = App-wallet (inherited from the parent provider).","example":1},"iconUrl":{"type":"string","example":"https://r2.example.com/provider-categories/ongaming.png"},"sortOrder":{"type":"integer","example":0}}},"EnvelopeProviderListResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"providers":{"type":"array","items":{"$ref":"#/components/schemas/ProviderItem"}}}}}}]},"ProviderItem":{"type":"object","properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"jili"},"code":{"type":"string","example":"jili"},"activeIconUrl":{"type":"string","example":""},"iconUrl":{"type":"string","example":""},"status":{"type":"boolean","example":false},"walletType":{"type":"integer","description":"Provider wallet type. Frontend uses this to branch the launch UX:\n  - `1` = seamless (game list → tap game → embedded launch URL)\n  - `2` = transfer  (game list → tap game → embedded launch URL, deposit/withdraw)\n  - `3` = App       (no game list — single tile → POST /v1/user/service/launch\n                     with `provider_id`; response includes `username`/`password`\n                     + a deep-link `login_url` for the casino app)\n","example":1},"isEvent":{"type":"boolean","description":"Event provider. When `true`, this provider is only launchable by players with an active\nin-progress promotion; the frontend should grey it out for guests and non-promotion users.\n","example":false},"categories":{"type":"array","items":{"type":"object","properties":{"providerCategoryId":{"type":"integer","example":2},"name":{"type":"string","example":"JILI - FISHING"},"serviceCategoryId":{"type":"integer","example":5},"iconUrl":{"type":"string","example":""}}}}}},"EnvelopeProviderCategoriesResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/ProviderCategoryDetailItem"}}}}}}]},"ProviderCategoryDetailItem":{"type":"object","properties":{"id":{"type":"integer","example":5},"name":{"type":"string","example":"PRAGMATIC PLAY - LIVE"},"provider_id":{"type":"integer","example":500001},"provider_name":{"type":"string","example":"THEONE"},"service_category_id":{"type":"integer","example":2},"category_name":{"type":"string","example":"Live Casino"},"status":{"type":"boolean","example":true},"icon_url":{"type":"string","example":""},"wallet_type":{"type":"integer","description":"`1` = seamless, `2` = transfer, `3` = App-wallet (frontend renders App-wallet\ncategories as a single launchable tile — no game list).\n","example":2},"sort_order":{"type":"integer","example":0},"aggregator":{"type":"string","description":"Brand key — a \"brand\" is the `(provider_id, aggregator)` tuple. Opaque string\n(e.g. `\"0\"` for a direct provider). Group categories by it to build brand tiles.\n","example":"5"},"is_event":{"type":"boolean","description":"Inherited from the parent provider. When `true`, only launchable by players with an\nactive in-progress promotion; grey it out for guests and non-promotion users.\n","example":false},"is_iframe":{"type":"boolean","nullable":true,"description":"Whether this brand's games embed in an iframe. Tri-state: `null` = untested,\n`true` = embeds, `false` = blocked. Set centrally via BO Central\n`POST /v1/central/game-catalog/brand-iframe`.\n","example":true},"slug":{"type":"string","description":"SEO brand slug from `provider_categories.slug` (e.g. `pp`), unique per provider.\nUsed for the SEO route\n`/v1/user/{provider_id}/{provider_category_slug}/{service_category_slug}`.\n","example":"pp"}}},"EnvelopePopularServicesResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"services":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ServiceItem"},{"type":"object","properties":{"totalPlays":{"type":"integer","example":150}}}]}}}}}}]},"EnvelopeRecentServicesResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"services":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ServiceItem"},{"type":"object","properties":{"lastPlayedAt":{"type":"string","format":"date-time","example":"2026-02-26T00:00:00+08:00"}}}]}}}}}}]},"LaunchServiceRequest":{"type":"object","description":"Launch request — **exactly one of `service_id` or `provider_id` must be set**:\n\n- `service_id` — the standard launch path. Use for transfer/seamless wallets\n  (the user picks a specific game). Also valid for App-wallet (caller picks the\n  App-wallet provider's single service row).\n- `provider_id` — App-wallet shortcut. Use when the user clicks an App-wallet\n  provider tile and there's no game list to drill into. The backend resolves\n  the single services row belonging to that provider and runs the standard\n  launch flow. Rejected with 400 if the provider's `wallet_type` is not 3 (App).\n\nSetting both, or neither, returns a 400 InvalidArgument.\n","properties":{"service_id":{"type":"integer","format":"int64","description":"ID of the service/game to launch. Required for transfer/seamless wallets; optional for App-wallet (use `provider_id` instead).","example":10},"provider_id":{"type":"integer","format":"int64","description":"App-wallet shortcut — resolves to the single service for that provider. Only valid for `wallet_type=3` providers.","example":500003},"amount":{"type":"string","nullable":true,"description":"Amount to transfer to provider (optional)","example":"100.00"}}},"EnvelopeLaunchServiceResponse":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"login_url":{"type":"string","description":"Game login redirect URL or deep link URI","example":"https://game.jili.com/launch/abc123"},"username":{"type":"string","nullable":true,"description":"For app-type providers (wallet_type 3)"},"password":{"type":"string","nullable":true,"description":"For app-type providers (wallet_type 3)"},"download_url":{"type":"string","nullable":true,"description":"APK/app download link (wallet_type 3)"}}}}}]},"RestoreBalanceRequest":{"type":"object","properties":{"provider_id":{"type":"integer","format":"int64","description":"Provider ID (optional, restore from specific provider)","example":1}}},"StorePromotionRequest":{"type":"object","required":["title","description","bonus_type","bonus_value","start_date"],"properties":{"promotion_category_id":{"type":"string","description":"Promotion category ID (ULID, optional)"},"title":{"type":"string","maxLength":255,"example":"Welcome Bonus 100%"},"description":{"type":"string","example":"Get 100% bonus on your first deposit"},"terms_conditions":{"type":"string","nullable":true},"bonus_type":{"type":"integer","description":"1=percentage, 2=fixed amount, 3=random","enum":[1,2,3],"example":1},"bonus_value":{"type":"number","minimum":0,"example":100},"max_payout":{"type":"number","nullable":true,"minimum":0,"example":5000},"max_withdrawal":{"type":"number","nullable":true,"minimum":0,"example":50},"turnover":{"type":"number","nullable":true,"minimum":0,"example":20},"winover":{"type":"number","nullable":true,"minimum":0},"turnover_type":{"type":"integer","nullable":true,"description":"1=multiplier, 2=fixed amount","enum":[1,2]},"claim_condition_type":{"type":"integer","nullable":true,"description":"1=deposit, 2=free, 3=custom","enum":[1,2,3]},"claim_conditions":{"type":"object","nullable":true,"description":"Claim conditions as an object (not JSON string):\n- type 1 (deposit): { \"min_deposit\": 100 }\n- type 2 (free): {}\n- type 3 (custom): { \"min_deposit_amount\": 100, \"min_deposit_count\": 1 }\n"},"provider_category_ids":{"type":"array","nullable":true,"items":{"type":"integer"},"description":"Array of provider category IDs","example":[1,3,5]},"start_date":{"type":"string","format":"date-time","example":"2026-01-01T00:00:00+08:00"},"end_date":{"type":"string","format":"date-time","nullable":true,"example":"2026-12-31T23:59:59+08:00"},"banner_image":{"type":"string","format":"binary","description":"Banner image file (jpg, jpeg, png, webp; max 5MB)"},"promo_image":{"type":"string","format":"binary","description":"Promotion image file (jpg, jpeg, png, webp; max 5MB)"},"min_topup_amount":{"type":"number","nullable":true,"minimum":0},"max_topup_amount":{"type":"number","nullable":true,"minimum":0},"min_times_of_topup":{"type":"integer","nullable":true,"minimum":0},"claim_limit":{"type":"integer","nullable":true,"minimum":0},"claim_reset":{"type":"integer","nullable":true,"description":"0=none, 1=daily, 2=weekly","enum":[0,1,2]},"initial_free_limit":{"type":"integer","nullable":true,"minimum":0},"deposit_free_limit":{"type":"integer","nullable":true,"minimum":0},"is_clearable":{"type":"boolean","nullable":true},"display_type":{"type":"integer","nullable":true,"description":"1=icon, 2=banner"},"sort_order":{"type":"integer","nullable":true},"status":{"type":"integer","nullable":true,"description":"0=inactive, 1=active","enum":[0,1]}}},"UpdatePromotionRequest":{"type":"object","description":"Only provided fields are applied (partial update). All fields are optional.","properties":{"promotion_category_id":{"type":"string","nullable":true},"title":{"type":"string","nullable":true,"maxLength":255},"description":{"type":"string","nullable":true},"terms_conditions":{"type":"string","nullable":true},"bonus_type":{"type":"integer","nullable":true,"enum":[1,2,3]},"bonus_value":{"type":"number","nullable":true,"minimum":0},"max_payout":{"type":"number","nullable":true,"minimum":0},"max_withdrawal":{"type":"number","nullable":true,"minimum":0},"turnover":{"type":"number","nullable":true,"minimum":0},"winover":{"type":"number","nullable":true,"minimum":0},"turnover_type":{"type":"integer","nullable":true,"enum":[1,2]},"claim_condition_type":{"type":"integer","nullable":true,"enum":[1,2,3]},"claim_conditions":{"type":"object","nullable":true},"provider_category_ids":{"type":"array","nullable":true,"items":{"type":"integer"}},"start_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true},"banner_image":{"type":"string","format":"binary","description":"Banner image file (jpg, jpeg, png, webp; max 5MB)"},"promo_image":{"type":"string","format":"binary","description":"Promotion image file (jpg, jpeg, png, webp; max 5MB)"},"min_topup_amount":{"type":"number","nullable":true,"minimum":0},"max_topup_amount":{"type":"number","nullable":true,"minimum":0},"min_times_of_topup":{"type":"integer","nullable":true,"minimum":0},"claim_limit":{"type":"integer","nullable":true,"minimum":0},"claim_reset":{"type":"integer","nullable":true,"enum":[0,1,2]},"initial_free_limit":{"type":"integer","nullable":true,"minimum":0},"deposit_free_limit":{"type":"integer","nullable":true,"minimum":0},"is_clearable":{"type":"boolean","nullable":true},"display_type":{"type":"integer","nullable":true},"sort_order":{"type":"integer","nullable":true},"status":{"type":"integer","nullable":true,"enum":[0,1]}}},"CreatePromotionCategoryRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Welcome Bonus"},"description":{"type":"string","nullable":true},"sort_order":{"type":"integer","example":0},"banner_url":{"type":"string","nullable":true},"status":{"type":"integer","enum":[0,1],"example":1}}},"UpdatePromotionCategoryRequest":{"type":"object","description":"Only provided fields are applied (partial update).","properties":{"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"sort_order":{"type":"integer","nullable":true},"banner_url":{"type":"string","nullable":true},"status":{"type":"integer","nullable":true,"enum":[0,1]}}},"SaveProviderCredentialRequest":{"type":"object","required":["provider_id","api_url","credential_fields","status","env"],"properties":{"provider_id":{"type":"integer","format":"int64","example":1},"api_url":{"type":"string","format":"url","maxLength":500,"example":"https://api.jili.com/v1"},"credential_fields":{"type":"string","description":"JSON string of credential key-value pairs (must be valid JSON)","example":"{\"agent_id\":\"AG123\",\"agent_key\":\"secret-key-here\"}"},"status":{"type":"boolean","example":true},"env":{"type":"string","enum":["staging","production"],"example":"staging"},"kiosk_url":{"type":"string","nullable":true,"maxLength":500},"kiosk_username":{"type":"string","nullable":true,"maxLength":255},"kiosk_password":{"type":"string","nullable":true,"maxLength":255,"description":"Will be encrypted if provided"},"remark":{"type":"string","nullable":true,"maxLength":1000},"provider_categories":{"type":"array","nullable":true,"items":{"type":"object","required":["category_id","status"],"properties":{"category_id":{"type":"integer","format":"int64","example":1},"status":{"type":"boolean","example":true}}}}}}}}}