Player Balance Reclaim

The Agent system can call this API to actively reclaim all local remaining balances for the player and currency across every Provider in the VCT platform (e.g. when the player exits the lobby).

Upon calling this API, VCT aggregates every local wallet for the player and currency, moves them into pending settlement, waits for the settlement window, and triggers the Offline / Balance Reclaim Callback (/api/v1/callback/offline) with the aggregate amount for the Agent system.

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/player/reclaim
Authentication	Agent Token (Bearer)
Content-Type	application/x-www-form-urlencoded

Request Parameters

Parameter	Type	Required	Description
member_id	string	Yes	Unique player ID in the Agent system
currency	string	Yes	The currency code to reclaim (e.g. MYR).
session_id	string	Yes	The VCT session ID returned by the game launch response. It must be returned unchanged to identify the exact session being reclaimed.

Request Example

curl -X POST https://api.example.com/papi/v1/player/reclaim \
  -H "Authorization: Bearer {agent_token}" \
  -d "member_id=player_001&currency=MYR&session_id=vct-session-uuid-001"

Response Fields

Data Field Structure

Field	Type	Description
member_id	string	Player ID in the Agent system
reclaimed_amount	decimal	Final amount; it is not included in the initial settling response and is sent later through /api/v1/callback/offline
session_id	string	VCT session ID associated with this reclaim
currency	string	Currency code (returns an empty string if no active balance exists)
action	string	Reclaim action, normally exit_game for an active reclaim
settlement_status	string	Initial response is settling; completed means the Agent acknowledged Offline; callback_failed means acknowledgement failed

An outer code=0 only means that Hub accepted and executed the reclaim request. It does not by itself mean that the Redis settlement lock was released. The Agent must check data.settlement_status.

All Provider wallets for the same currency are cleared as one reclaim. Force Kick uses the same aggregate rule.

Accepted Response (settling)

VCT accepts the request immediately. It does not wait for the settlement window or guess the final amount:

{
  "status": true,
  "code": 0,
  "data": {
    "member_id": "player_001",
    "currency": "MYR",
    "session_id": "vct-session-uuid-001",
    "action": "exit_game",
    "settlement_status": "settling"
  },
  "msg": "success"
}

The final reclaimed_amount appears only in the later /api/v1/callback/offline request. The Agent must not treat code=0 or settlement_status=settling as completed settlement.

Settlement Completed

After the settlement window has elapsed, Hub has calculated the final amount, and the Agent has successfully acknowledged /api/v1/callback/offline, Hub marks the session as completed. If the Agent later sends another reclaim request with the same session_id, Hub returns the confirmed final amount:

{
  "status": true,
  "code": 0,
  "data": {
    "member_id": "player_001",
    "currency": "MYR",
    "session_id": "vct-session-uuid-001",
    "action": "exit_game",
    "reclaimed_amount": 100.00,
    "settlement_status": "completed"
  },
  "msg": "success"
}

This is not the response to the initial reclaim request. The initial request must return settling; the final amount is first delivered asynchronously through /api/v1/callback/offline. A later request with the same session_id can then return completed and reclaimed_amount.

Failed Response

{
  "status": false,
  "code": 7,
  "data": {},
  "msg": "player_not_found"
}

When Offline is not acknowledged

If data.settlement_status is callback_failed, the Agent did not successfully acknowledge Hub's /api/v1/callback/offline. Hub keeps the same-currency settlement lock until its derived TTL expires; an administrator can also retry with the same session_id from Player Sessions. The Agent must keep processing idempotent by session_id.

AI Implementation Prompt (Copy Ready)

Implement the VCT Player Balance Reclaim flow in the current Agent project.

Endpoint: POST {VCT_BASE_URL}/papi/v1/player/reclaim
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {agent_token}
Required: member_id, currency, session_id. Preserve the session_id returned by Game Launch.

Requirements:
1. Use Agent + member_id + currency + session_id as the idempotency identity and create a settlement-pending state.
2. code=0 only means the request was accepted; always inspect data.settlement_status.
3. settling is asynchronous and has no final amount. completed means the Agent acknowledged offline. callback_failed means offline is still unacknowledged.
4. Obtain the final reclaimed_amount from the later offline callback for the same session. Never credit twice on repeated reclaim/offline calls.
5. Repeating reclaim for the same session must return the existing state instead of creating a second flow.
6. After a timeout, retry with the same idempotency identity and never invent a new session_id.
7. Keep credentials out of logs; record member_id, currency, session_id, business code, and settlement_status.
8. Test settling, completed, callback_failed, duplicates, invalid session, timeout, player not found, and offline retry.

Reuse existing sessions, locks, HTTP client, and error handling. Implement backend state management, UI status, and tests.