Game Rates Query

Brand identity: this endpoint uses the same brand_guid as the catalogue and bet-push, and returns brand_guid, brand_code, and brand_name without brand. Use brand_guid for exact filtering; the existing brand request field searches current master Code or Name. Deploy the updated Hub backend before migrating. Commission formulas, priority, effective dates, and historical versions are unchanged.

Use this endpoint to query commission rates by Brand, currency, game type, and business date, or retrieve every available combination.

Endpoint

POST /papi/v1/game/rates with Authorization: Bearer {agent_token} and Content-Type: application/json.

Production: https://hub-panel-api.v7stech.com
Test: https://hub-panel-api-dev.v7stech.com

All request fields are optional. Send {} for all currently accessible rates applicable today. Combined filters intersect; an unknown GUID returns an empty list rather than all Brands.

Field	Description
brand_guid	Recommended exact Brand GUID filter, trimmed before matching
brand	Case-insensitive search of current Brand Code or Name; may match several Brands
currency	Currency such as MYR; case-insensitive
game_genre	Numeric game genre: 2 Slot, 3 Fish, 4 Sport, 5 Card, 6 Live, 7 Other
as_of_date	Business date in YYYY-MM-DD; defaults to today

Each data.list item contains brand_guid, brand_code, brand_name, currency, numeric game_genre, display-only game_genre_name, percentage string rate, rate_version_id, and effective_from when a version exists. The response also contains data.rate_unit = "percent" and the resolved data.as_of_date. A 0.00 rate is valid.

Rates are grouped by brand_guid + currency + game_genre. Distinct GUIDs with identical names, codes, or rates remain separate. Code and Name come from current master data; as_of_date selects the rate version. Missing, deleted, disabled, empty-code, or wrongly owned Brands are omitted. Current game authorization and enabled currencies still limit the query.

Bet-push now includes numeric game_genre and display-only game_genre_name; its existing game_type remains provider-native and must not drive commission. A product with mixed genres and no uniquely matched game code yields game_genre=0 and an empty name. Hold such wagers for reconciliation until the settlement policy is agreed; never guess a genre from raw type or Product Code.

Rate fallback order

Currency is the outer dimension. Within one currency, the most specific applicable rule wins:

Provider + Brand + Game Type
  → Provider + Brand
  → Provider
  → Global

An internal game_genre=0 means the default rate for that Brand and currency; it is not a missing rate. If a wager has a concrete type such as 2 but no Brand + Currency + 2 override exists, apply the same Brand/currency rule whose game_genre is 0. Use currency_code="*" (All Currencies) only after rules for the concrete currency fail at the applicable scope. Report a missing rate only when the complete fallback chain has no applicable rule.

Daily Commission Rule

The platform calculates the preceding UTC+8 business day from 00:00:00 inclusive to the next 00:00:00 exclusive, independently for each brand_guid + currency + game_genre.

daily_net_loss = daily_bet_amount - daily_win_amount
daily_commission = 0                               if daily_net_loss <= 0
daily_commission = daily_net_loss × daily_rate/100 if daily_net_loss > 0

Use decimal/BigDecimal for money. A winning day does not offset commission produced on another day. Monthly payable commission is the sum of the month's daily commission rows.

Rate changes require an effective date, no earlier than the following day, and start at 00:00 on that date. Every version retains its operator, timestamp, and reason.

The Agent must query the preceding business date with as_of_date, calculate its daily commission, and persist rate, rate_version_id, effective_from, as_of_date, fetch time, and the raw response. Use date + brand_guid + currency + game_genre as the idempotency key.

For late wagers or reversals in an open month, recalculate the original business day with that day's historical rate. After month close, preserve the closed row and create an auditable post_close_adjustment_pending; never silently move it into the current month.

AI Implementation Prompt

Integrate POST {VCT_BASE_URL}/papi/v1/game/rates in the current Agent backend. Reuse the server-side Bearer-token implementation and never expose credentials to the browser or ordinary logs.

Optional fields are brand_guid, brand, currency, game_genre, and as_of_date. Use the catalogue or wager brand_guid for exact filtering; brand only searches current master Code or Name and is not unique. When calculating a business day, send that date as YYYY-MM-DD as_of_date. Use only 2–7 for classified games; 0/1/8/unknown have an empty display name.

Each row returns brand_guid, brand_code, brand_name, currency, game_genre, game_genre_name, rate, and optional rate_version_id/effective_from; no brand response field. Use decimal/BigDecimal. For every UTC+8 calendar day and each brand_guid + currency + game_genre: daily_net_loss = daily_bet_amount - daily_win_amount; commission is zero when daily_net_loss <= 0, otherwise daily_net_loss × rate / 100. A winning day does not offset another day. Monthly payable is the sum of daily rows.

Persist an immutable daily rate snapshot containing brand_guid, brand_code, brand_name, rate, rate_version_id, effective_from, as_of_date, fetch time, and raw response. Make the task idempotent with date + brand_guid + currency + game_genre. Treat 0.00 as valid; stop and notify operations on a missing or conflicting rate. Recalculate late open-month events on their original business date; create post_close_adjustment_pending after close. Preserve historical Code/Name snapshots after Brand renames. Backfill old GUID-less records only through confirmed unambiguous mappings, never by guessing names. Preserve commission formulas, priority, and wallet handling. Test same-name/code Brands with different GUIDs, exact GUID filtering, rename snapshots, historical dates, the effective-date boundary, zero rates, daily win/loss/break-even, retries, reversals, empty results, business errors, timeouts, and 5xx.