Game Launch

Get game launch URL for players to enter real-money games.

Environment URLs

Environment	Base URL
Production	https://hub-panel-api.v7stech.com
Staging	https://hub-panel-api-dev.v7stech.com

Endpoint

Property	Value
Path	POST /papi/v1/game/launch
Auth	Agent Token (Bearer)
Content-Type	application/x-www-form-urlencoded

Request Parameters

Parameter	Type	Required	Description
member_id	string	Yes	Player unique identifier (Agent-side ID). Only English letters and digits are allowed; uppercase letters are automatically converted to lowercase by Hub. Spaces, underscores, hyphens, and other symbols are rejected.
game_id	string	Yes	Game ID (from Game List API)
currency	string	Yes	Currency code (e.g. MYR, USD). Automatically converted to uppercase
platform	string	No	Platform type: WEB / MOBILE / DESKTOP, default WEB. Automatically converted to uppercase
language	string	No	Language code, default en-US
return_url	string	No	URL to redirect after game exit

Automatic Setup

When a player launches a game for the first time:

1. The player is automatically registered with the game provider (no separate call needed)
2. A wallet with balance=0 is automatically created for the specified currency (if not already exists)

Switching Games in the Same Currency

If the player is already in another game for the same currency, the new launch is not rejected. Hub first aggregates and clears every Provider wallet, including late payouts, and sends one switch_game Offline callback. Whether the Agent callback succeeds or fails, it does not block the new launch. Hub then best-effort closes the old session and returns the new game URL with a new session_id. Use only this new session_id for later balance sync and callbacks.

Request Example

curl -X POST https://api.example.com/papi/v1/game/launch \
  -H "Authorization: Bearer {agent_token}" \
  -d "member_id=player001&game_id=xxxx-guid&currency=MYR&platform=WEB&language=en-US"

Response Fields

Field	Type	Description
game_url	string	Game launch URL (redirect player to this URL to enter game)
session_id	string	Unique VCT session ID. Store it and use it to reconcile balance, wager pushes, and offline reclaim.

Response Example

{
  "status": true,
  "code": 0,
  "data": {
    "game_url": "https://game.provider.com/play?token=xxx&lang=en-US",
    "session_id": "vct-session-uuid-001"
  },
  "msg": "success"
}

Error Codes

Code	Message	Description
1001	err.param.invalid	Required parameters missing (member_id, game_id, currency)
1002	err.signature.invalid	Agent Token verification failed
2006	err.player.member_id_invalid	Invalid member_id format: English letters and digits only; spaces and symbols are not allowed
2001	err.player.not_found	Player not found (must register first)
4001	err.game.not_found	Game not found or offline
4005	err.game.launch_failed	Game launch failed (provider registration or internal error)
4006	err.game.access_denied	Game-launch access validation failed. Use msg to identify whether the game does not support the currency, the agent currency is disabled, the brand does not support the currency, a commission rate is missing, or the game is unauthorized. See Error Codes.
5002	err.provider.call_failed	Game provider API call failed

Currency Launch Prerequisites

currency must be an actual currency returned for that game by Game List. For provider games marked ALL, Hub resolves the marker to its final launchable currency set during Game List; ALL itself cannot be used to launch.

Launch also verifies that the currency is globally enabled in Currency Management, supported by the game and Brand, allowed for the Agent, and covered by an applicable commission rate. A failure at any stage returns 4006; correct the configuration indicated by msg rather than retrying.

Launch Failure and Balance Compensation

Game launch is successful only when VCT returns code=0, a non-empty game_url, and a confirmed session_id. Receiving a successful /balance callback alone does not mean that the game launch succeeded.

If /balance succeeds but the provider launch fails, VCT sends action: "launch_failed" to /api/v1/callback/offline with the original session_id and reclaimed_amount. The Agent must release only the temporary session and lock; it must not process this as normal offline settlement or credit the player more than once.

AI Implementation Prompt (Copy Ready)

Implement the VCT real-money Game Launch flow in the current Agent project.

Endpoint: POST {VCT_BASE_URL}/papi/v1/game/launch
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {agent_token}, generated server-side.
Required fields: member_id, game_id, currency. Optional: platform, language, return_url.

Requirements:
1. Allow only letters and digits in member_id. Uppercase currency and platform. game_id must come from the VCT Game List id.
2. Prevent concurrent launches for the same Agent, player, and currency.
3. Mark launch successful only when HTTP succeeds, code=0, data.game_url is non-empty, and data.session_id is non-empty.
4. Persist the exact VCT session_id with player, currency, and game_id; reuse it for reclaim, bet-push, and offline.
5. A successful /balance callback is launch preparation only; do not record enter_game until requirement 3 succeeds.
6. For offline action=launch_failed, release only the matching temporary session/lock and never credit the wallet as a normal exit.
7. Surface code=4006 msg for currency, brand, commission, or game-access diagnosis. Do not retry configuration errors.
8. Retry transient network/5xx failures carefully and use an idempotency/request record to avoid duplicate launches after uncertain results.
9. Never expose credentials, the full Token, or sensitive query tokens from game_url in logs.
10. Test validation, success, missing URL/session ID, concurrency, 4006, timeout, and launch_failed compensation.

Reuse existing auth, HTTP client, session, and locking components. Deliver service/controller, redirect flow, and tests.