Bet Data Push Callback

VCT Platform batch-pushes settled bet data to the Agent (Operator).

Note

This API is called by the VCT Platform to the Agent (Operator) to push or batch-push wager logs and report data.

NOTE (Important for Transfer Wallet mode): In Transfer Wallet mode, this API is the only channel for the Agent system to retrieve all game betting, payout, cancellation, and rollback logs. All logs during gameplay (including bet placements BET, settled wagers SETTLED, extra bonus payouts BONUS, and cancels/rollbacks CANCEL/ROLLBACK/REFUND/VOID) will be unified and pushed to this endpoint. The Agent system only needs to receive and record these logs for reporting purposes, without modifying the player's live balance.

Endpoint

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

Request Parameters (from VCT)

Parameter	Type	Required	Description
operator_code	string	Yes	Operator code
wagers	array	Yes	Wager list
wagers[].username	string	Yes	Raw player username (without VCT platform agent prefix)
wagers[].currency	string	Yes	Currency code (e.g., MYR, VND, USD, used to locate the player's currency-specific wallet)
wagers[].bet_id	string	Yes	Bet ID
wagers[].game_code	string	Yes	Game code
wagers[].game_type	string	Yes	Game type
wagers[].bet_amount	decimal	Yes	Bet amount
wagers[].valid_bet_amount	decimal	Yes	Valid bet amount
wagers[].prize_amount	decimal	Yes	Prize amount
wagers[].win_loss	decimal	Yes	Win/loss amount
wagers[].status	string	Yes	Wager status/action: BET / SETTLED / CANCEL / VOID / ROLLBACK / REFUND / BONUS
wagers[].bet_time	string	Yes	Bet time
wagers[].settle_time	string	Yes	Settlement time
wagers[].round_id	string	No	Round ID
wagers[].original_transaction_id	string	No	Original settlement/bet transaction ID; recommended for status=BONUS or correction records (e.g., CANCEL)
sign	string	Yes	Signature
timestamp	long	Yes	Timestamp

Response Fields

Field	Type	Description
received	int	Number of records received
status	string	Processing status

Example Request

Settled Wager SETTLED

{
  "operator_code": "AG",
  "wagers": [
    {
      "username": "player001",
      "currency": "MYR",
      "bet_id": "settle-20260706-0001",
      "provider_code": "GSC",
      "provider_name": "Game Science",
      "brand_code": "PG",
      "brand_name": "Pocket Games Soft",
      "game_code": "PG-SLOT-001",
      "game_type": "SLOT",
      "bet_amount": 100.0,
      "valid_bet_amount": 100.0,
      "prize_amount": 200.0,
      "win_loss": 100.0,
      "status": "SETTLED",
      "bet_time": "2026-07-06T10:00:00+08:00",
      "settle_time": "2026-07-06T10:01:00+08:00",
      "round_id": "round-10001"
    }
  ],
  "sign": "demo-sign",
  "timestamp": 1783325100
}

Extra Bonus Record BONUS

{
  "operator_code": "AG",
  "wagers": [
    {
      "username": "player001",
      "currency": "MYR",
      "bet_id": "bonus-20260706-0001",
      "provider_code": "GSC",
      "provider_name": "Game Science",
      "brand_code": "PG",
      "brand_name": "Pocket Games Soft",
      "game_code": "PG-SLOT-001",
      "game_type": "SLOT",
      "bet_amount": 0.0,
      "valid_bet_amount": 0.0,
      "prize_amount": 30.0,
      "win_loss": 30.0,
      "status": "BONUS",
      "bet_time": "2026-07-06T10:01:00+08:00",
      "settle_time": "2026-07-06T10:01:10+08:00",
      "round_id": "round-10001",
      "original_transaction_id": "settle-20260706-0001"
    }
  ],
  "sign": "demo-sign",
  "timestamp": 1783325160
}

Example Response

{
  "received": 1,
  "status": "success"
}
```## Push Logic & Processing Recommendations

### 1. Purely for Reporting/Ledger Purposes (CRITICAL)
* **No Real-Time Balance Operations**: Under **Transfer Wallet Mode**, the player's actual available balance has already been fully deducted by `/bet` upon game launch and returned by `/settle` upon exit. Therefore, every wager log pushed via `/bet-push` **is purely for report statistics and gaming commission calculations. The Agent system MUST NOT add or subtract from the player's live wallet balance based on these logs**, otherwise balance discrepancies and duplicate bookkeeping will occur.

### 2. Idempotency Check
* The Agent system should use `wagers[].bet_id` as the unique key to filter out duplicate logs, ensuring wagers are not reported twice in case of network retries.

### 3. Wager Status and Correction Flow
* **Normal Statuses**: `BET` (raw bet placement), `SETTLED` (normal settled wager), `BONUS` (extra payout/jackpot).
* **Correction/Rollback Statuses**: `CANCEL`, `ROLLBACK`, `REFUND`, `VOID`.
* **Correction Flow Handling**: When the wager status is a rollback/correction status, VCT will provide the `original_transaction_id` pointing to the original bet/settle ID. The Agent should locate the original report log by this ID and update its win/loss and status accordingly to maintain report accuracy.

### 4. Automatic Retry Mechanism and Response Codes
* **Successful Processing**: Return a `HTTP 200` status code with `{"received": 1, "status": "success"}`. VCT's queue worker will mark this task as successfully delivered.
* **Retry Guarantee**: If the Agent's database is busy or has transient errors, return `HTTP 5xx` or let the request timeout. VCT's delivery queue will **automatically retry pushing the log** over subsequent intervals to guarantee zero log loss.

## Provider Source Mapping

| Provider | Callback Path | Request Format |
|----------|--------------|----------------|
| BG | — | Push not supported |
| GSC | `seamless/pushbetdata` | JSON, wagers array |
| SA | — | Push not supported (use query API to pull) |
| WM | `webhook` (cmd=SendMemberReport) | form-data, result array |