Active Game Balance Adjustment

Use this endpoint after the Agent has committed a late cross-game settlement, deposit, or reversal to its master wallet while the player remains in another game. Hub deduplicates retries by event_id and compares the source and current session wallet IDs. It applies the delta only when they are different; sessions sharing one physical Provider wallet are recorded without changing the balance again.

Endpoint

Property	Value
Path	POST /papi/v1/player/balance-adjust
Authentication	Agent Bearer Token
Content-Type	application/json or application/x-www-form-urlencoded

Request

Field	Type	Required	Description
member_id	string	Yes	Agent player ID
currency	string	Yes	Current game currency
session_id	string	Yes	Current active Hub session
event_id	string	Yes	Stable idempotency key; reuse it for every retry
event_type	string	Yes	For example settlement, deposit, void, or rollback
delta	decimal	Yes	Non-zero amount: positive credit or negative reversal
source_session_id	string	No	Source game session for a cross-game event
reverses_event_id	string	Required for negative delta	Original positive event being reversed

{
  "member_id": "player001",
  "currency": "MYR",
  "session_id": "uu-current-session",
  "event_id": "CMD_SETTLED_84000010943916399_v1",
  "event_type": "settlement",
  "delta": 50.00,
  "source_session_id": "cmd-old-session"
}

Hub changes only the current active game wallet. The response includes applied_delta, the amount actually applied, and same_wallet. When two Brands share the same Provider wallet, Hub returns same_wallet=true and applied_delta=0; the event remains durably idempotent and its reversal is also skipped. A duplicate request with the same event data returns the original result with idempotent=true. Reusing the ID with different business data returns event_id_conflict. A reversal must reference an applied positive event, cannot exceed its remaining amount, and cannot make the current wallet negative.

For session_mismatch, resolve the latest active session and retry the same event ID. For no_active_game_session, keep the committed Agent ledger entry and let the next game launch initialize Hub from the full master-wallet balance; do not append the old delta after that snapshot. For a timeout or player_settlement_in_progress, retry the exact same event through the Agent outbox.

Offline callbacks may contain both a source wallet and the amount mirrored into the current wallet. Reconcile using mirrored_adjustments.event_id and net_balance_to_reconcile; never credit wallet_cleared_total directly to the master wallet.