余额查询回调

VCT 平台查询玩家在包网（Agent）的余额。

说明

此接口由 VCT 平台调用。当玩家启动并进入游戏时，VCT 平台会调用此接口，查询玩家在包网（Agent）的可用余额，以准备进行后续的额度划转。包网（Agent）需实现此接口供 VCT 平台调用。

接口信息

属性	值
路径	POST /api/v1/callback/balance
调用方	VCT 平台 → 包网 (Agent)

请求参数（VCT 发送）

参数名	类型	必填	说明
username	string	是	玩家用户名
currency	string	否	货币代码
sign	string	是	请求签名
timestamp	long	是	请求时间戳

响应字段

字段	类型	必填	说明
status	string	是	处理状态：success（成功）/ player_not_found（玩家不存在） / error（系统错误）
balance	decimal	是	玩家当前可用余额（仅当 status 为 success 时有效）
currency	string	是	货币代码（当 status 为 success 时必填）
username	string	是	玩家用户名（当 status 为 success 时必填）

示例请求

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

示例响应

成功响应

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

玩家不存在 (拦截登录)

{
  "status": "player_not_found"
}

校验逻辑与处理建议

1. 强状态校验

• 必须返回 status：包网系统返回的响应中必须包含 status 字段。
• 拒绝进入游戏：若 status 缺失，或其值不为 "success"（例如为 "player_not_found"、"error" 等），VCT 平台会立即终止游戏加载流程并抛出登录异常。这避免了非合法或不存在的玩家进入游戏系统引起后续额度回收下分失败。

2. 账号状态校验建议

• 包网系统在接收到 /balance 查询时，建议对玩家账号的状态（如是否冻结、是否处于限制状态等）进行评估。如状态异常导致玩家不能进行游戏，可直接返回 {"status": "player_not_found"} 或 {"status": "error"} 从而阻止游戏启动。

游戏商来源映射

游戏商	回调路径	请求格式
BG	open.operator.user.balance	JSON-RPC 2.0（sn/sign/random）
GSC	seamless/balance	JSON（operator_code/sign/request_time）
SA	GetUserBalance	加密 URL-encoded body
WM	webhook（cmd=CallBalance）	form-data（cmd/signature/user）