{"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.1.0"},"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://virtserver.swaggerhub.com/ndm-c58/0WalletServices/3.1.0"},{"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"}],"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]}],"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/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`\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,"sort_order":0,"action":"game_list"},{"type":"provider_category","id":5,"name":"JILI - LIVE","wallet_type":1,"provider_id":1,"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","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,"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,"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,"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","providerId":1,"serviceCategoryId":3,"categoryName":"Slots","status":true,"iconUrl":"","walletType":1},{"id":100,"name":"lobbykiss","providerId":500003,"serviceCategoryId":9,"categoryName":"Casino App","status":true,"iconUrl":"","walletType":3},{"id":101,"name":"Pussy888","providerId":500004,"serviceCategoryId":9,"categoryName":"Casino App","status":true,"iconUrl":"","walletType":3}]}}}}},"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.\nFrontend uses this to grey out ineligible providers/categories in the game lobby.\nIf no active promotion, `active_game` is null.\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":{"activeGame":{"promotionId":1,"promotionName":"Welcome Bonus","allowedProviderCategoryIds":[1,3],"allowedCategoryIds":[1]}}}},"no_promotion":{"summary":"No active promotion","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/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\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":1,"code":"pussy888","name":"Pussy888","status":true,"tenant_provisioned":true,"categories":[{"id":10,"name":"Slots","service_category_id":3,"status":true,"tenant_provisioned":true,"services":[{"id":1001,"name":"Golden Empire","service_code":"GE001","status":true}]}]}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"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}}}}}}}},"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"}}}},"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},"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":1},"name":{"type":"string","example":"JILI - SLOTS"},"providerId":{"type":"integer","example":1},"serviceCategoryId":{"type":"integer","example":3},"categoryName":{"type":"string","example":"Slots"},"status":{"type":"boolean","example":true},"iconUrl":{"type":"string","example":""},"walletType":{"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":1}}},"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}}}}}}}}}