Balance Query Callback

VCT Platform queries the player's balance on the Agent (Operator) side.

Note

This API is called by the VCT Platform. When a player launches and enters the game, VCT calls this interface to query the player's available balance on the Agent side, in preparation for the subsequent credits transfer.

Endpoint

Property	Value
Path	POST /api/v1/callback/balance
Caller	VCT Platform → Agent (Operator)

Request Parameters (from VCT)

Parameter	Type	Required	Description
username	string	Yes	Player username
currency	string	No	Currency code
sign	string	Yes	Request signature
timestamp	long	Yes	Request timestamp

Response Fields

Field	Type	Required	Description
status	string	Yes	Processing status: success / player_not_found / error
balance	decimal	Yes	Player's current available balance (only valid when status is success)
currency	string	Yes	Currency code (required when status is success)
username	string	Yes	Player username (required when status is success)

Example Request

{
  "username": "player001",
  "currency": "MYR",
  "sign": "9a2f64d0bcfa829...",
  "timestamp": 1783324700
}

Example Response

Success Response

{
  "status": "success",
  "username": "player001",
  "currency": "MYR",
  "balance": 100.00
}

Player Not Found (Abort login)

{
  "status": "player_not_found"
}

Validation Logic & Processing Recommendations

1. Strict Status Verification

• Status Field is Mandatory: The response returned by the Agent system must contain the status field.
• Reject Game Access: If status is missing, or its value is not "success" (e.g. "player_not_found", "error", etc.), VCT Platform will immediately terminate the game launching process and throw a login exception. This prevents invalid or non-existent players from entering the game and causing subsequent wallet reclaim failures.

2. Player Account Checks

• It is recommended that the Agent system evaluates the player's account status (e.g., whether it is suspended, locked, etc.) during a /balance query. If the player is not allowed to play, return {"status": "player_not_found"} or {"status": "error"} to abort the launch.

Provider Source Mapping

Provider	Callback Path	Request Format
BG	open.operator.user.balance	JSON-RPC 2.0 (sn/sign/random)
GSC	seamless/balance	JSON (operator_code/sign/request_time)
SA	GetUserBalance	Encrypted URL-encoded body
WM	webhook (cmd=CallBalance)	form-data (cmd/signature/user)