Change Player BalanceChange Player Balance

Change a player's balance. This API is provided by the merchant (operator) and is called by the game platform.

Change player balance. This API interface is provided by the merchant (operator) for the gaming platform to call. The interface can be called multiple times: bet, cancel bet, payout, end game, etc.

This interface will be called multiple times: betting, canceling bets, awarding prizes, ending games, etc., each will trigger one call. Each call uses a different changeType value.

Each call has different changeType field values.

Request URL

POST {API_URL_ROOT}/player/changeBalance

Note: This URL can be configured in the merchant backend, but input and output parameters must meet the following requirements.

Request URLRequest Parameters

Header:

POST {API_URL_ROOT}/player/changeBalance

Note: This address can be configured in the merchant backend, but input and output parameters must meet the requirements belowName Required Type Description

sign Yes string Signature calculated using the signature algorithm (002.md).

Request Parameterstimestamp Yes int Unix timestamp in seconds, e.g. 1741837297.

Accept-Language Yes string Language code, see language list (017.md), e.g. zh,en, used for localized error messages.

Header ContentContent-Type Yes string application/json; charset=utf-8

Body:

| Parameter Name | Required | Type | Description |

| -------- | :----: | :----: | -------- |Name Required Type Description

| sign | Yes | string | Signature, calculated using signature algorithm |recordId Yes string Game record ID, unique identifier for each play.

| timestamp | Yes | int | Timestamp in seconds, seconds elapsed from January 1, 1970 to now, e.g.: 1741837297 |txId Yes string Transaction ID, unique per request.

| Accept-Language | Yes | string |Accepted language encoding, refer to language list, e.g.: zh,en, to provide corresponding language error messages when errors occur. |tenantId Yes int Merchant ID, unique integer assigned by the platform.

| Content-Type | Yes | string | "application/json; charset=utf-8" |userId Yes string Merchant’s player ID, unique per player.

gameId Yes int Game ID.

changeType Yes int Change type, enum described below.

betType Yes int Bet type, enum described below.

BODY Content **betAmount Yes double Bet amount.

bonus Yes double Payout amount.

| Parameter Name | Required | Type | Description |multiple No double Multiplier. Sometimes differs slightly from bonus/betAmount (e.g. capped maximum payout).

| -------- | :----: | :----: | -------- |roundId No string Round ID, mainly for multiplayer games.

| recordId | Yes | string | Game record ID, unique identifier for each player's game |area No int Area ID, default 0. Some games bet by area.

| txId | Yes | string | Transaction ID, unique identifier for each call request |currency No string Currency.

| tenantId | Yes | int | Merchant ID, unique integer assigned by the platform |isCompleted No bool Whether the game is completed. Required on payout. If last payout sets true, you need not call end game (changeType=4).

| userId | Yes | string | Merchant's player ID, ID that can distinguish each player |isRetry No bool Whether this is a retry. A request may timeout; up to 6 retries until success; retries set this true.

| gameId | Yes | int | Game ID |parentId No string Parent record ID. For slot free spins: if current record is a free spin, parentId is the original bet record ID; betType=3, betAmount=0 marks free spin.

| changeType | Yes | int | Change type, enumeration values listed in changeType description below |Different changeType values imply different field usages. Types: bet with immediate payout, normal bet, cancel bet, payout, end game, etc.

| betType | Yes | int | Bet type, enumeration values listed below |

| betAmount | Yes | double | Bet amount |Bet with immediate payout (changeType=0)

| bonus | Yes | double | Prize amount |betAmount has value; bonus=0 means no payout; bonus>0 means payout.

| multiple | No | double | Prize multiplier, sometimes this value may differ slightly from bonus/betAmount, e.g.: when preset specified multiplier withdrawal triggers maximum prize amount limit |multiple is payout multiplier; if absent system uses bonus / betAmount.

| roundId | No | string | Round ID, mostly used for multiplayer games, identifies unique ID for each game round |isCompleted=true ends this bet directly.

| area | No | int | Area ID, default is 0, some games have area betting to distinguish different areas |

| currency | No | string | Currency |Normal bet (changeType=1)

| isCompleted | No | bool | Whether completed, this value is required when awarding prizes. When awarding the last prize, you can directly set this field value=true, eliminating the need to call the end game request (changeType=4), reducing one request call |betAmount has value; bonus=0.

| isRetry | No | bool | Whether retry, sometimes a request may timeout or return normal results, triggering 6 retry attempts until successful results are returned. This value is true when retrying |

| parentId | No | string | Parent ID, for slot games that may trigger free spins. If the current record is a free spin record, parentId is the original bet record ID, with betType=3, betAmount=0 indicating free spin |Cancel bet (changeType=2)

betAmount is original bet amount.

With different changeType values, the values of each field will also differ. There are 4 types: normal betting, cancel betting, awarding prizes, game ending, etc.Payout (changeType=3)

betAmount=0; bonus has value.

  1. Bet and award scenario, changeType=0May be called multiple times for some games.

    betAmount field has value, bonus field value is 0, if bonus field value >0 then there is a prize award, =0 means no prize awardmultiple same rule as above.

    multiple field is the prize multiplier. If there is a value, use this value; if not, the system will calculate using bonus/betAmountFinal payout can set isCompleted=true instead of extra changeType=4 call.

    isCompleted field value=true, directly ends this bet

    End game (changeType=4)

  2. Normal betting scenario, changeType=1betAmount=0; bonus=0.

    betAmount field has value, bonus field value is 0

Slot free spin (changeType=0)

  1. Cancel betting scenario, changeType=2betType=3 marks free spin; parentId is original bet record ID. Free spin may trigger multiple payouts; each payout uses a different recordId.

    betAmount field has value, the amount when betting

Examples (6 cases):

  1. Prize awarding scenario, changeType=3

    betAmount field value is 0, bonus field has valueResponse Parameters

    Prize awarding, some games may have multiple callsName Required Type Description

    multiple field is the prize multiplier. If there is a value, use this value; if not, the system will calculate using bonus/betAmounttenantId Yes int Merchant ID.

    For the last prize award, you can set isCompleted=true, indicating that this game round has ended, which has the same effect as calling this interface again with changeType=4userId Yes string Merchant’s user ID.

balance No double Player balance. Must always return current balance and update it, regardless of success.

  1. End game scenario, changeType=4currency No string Currency.

    betAmount field value is 0, bonus field value is 0Note: Regardless of isSuccess true or false, you must correctly return current balance. The system updates the account balance using this value. If account status abnormal (cannot play), balance must be 0.

  1. Slot game free spin trigger scenario, changeType=0Examples:

    betType=3 indicates this bet is a free spin, and parentId has value, which is the original bet record ID that triggered this free spin. Free spins may have multiple prize awards, each with different recordId

    betType Values

Value Description

Examples1 Normal bet

2 Cascading (chain elimination)

Total of 6 scenarios3 Free spin

4 Re-spin

```jsonchangeType Values

//Bet and award scenario:Value Description

{0 Bet with payout

"recordId": "682ed6edce1c812d736c4876",1 Normal bet

"txId": "682ed6edce1c812d736c4877",2 Cancel bet

"tenantId": 2317,3 Payout

"userId": "t20339",4 End game

"gameId": 2001,Game Flow Examples

"changeType": 0,For scenarios not using immediate bet with payout:

"betType": 0,

"betAmount": 100.00,Normal bet with payout

"bonus": 30,Bet -> Payout (isCompleted=true); changeType: 1 -> 3. Player bets, wins, settles, round ends. Recommended (last payout sets isCompleted=true, saves one call).

"multiple": 0.30,Bet -> Payout -> End game; changeType: 1 -> 3 -> 4.

"roundId": "12353",

"area": 0,Cancel bet

"currency": "BRL",Bet -> Cancel; changeType: 1 -> 2. Player cancels before round actually starts (common in multi-player or mini games). recordId same.

"details": null,

"isCompleted": trueNo payout

}Bet -> No win -> End game; changeType: 1 -> 4.

//Normal betting scenario:

{Single bet, multiple payouts

"recordId": "682ed6edce1c812d736c4876",Common in cascading slot, special slot features, lottery-type.

"tenantId": 2317,Bet -> Payout -> Payout -> ... -> Payout (isCompleted=true); changeType: 1 -> 3 -> 3 -> ... -> 3 (last with isCompleted=true, recommended).

"userId": "t20339",Or Bet -> Payout -> Payout -> ... -> End game; changeType: 1 -> 3 -> 3 -> ... -> 4. "gameId": 2001, "changeType": 1, "betType": 1, "betAmount": 100.00, "bonus": 0, "multiple": 0, "roundId": "12353", "area": 0, "currency": "BRL", "details": null, "isCompleted": false }

//Cancel betting scenario: { "recordId": "682ed6edce1c812d736c4876", "tenantId": 2317, "userId": "t20339", "gameId": 2001, "changeType": 2, "betType": 1, "betAmount": 100.00, "bonus": 0, "multiple": 0, "roundId": "12353", "area": 0, "currency": "BRL", "details": null, "isCompleted": false }

//Prize awarding scenario: { "recordId": "682ed6edce1c812d736c4876", "tenantId": 2317, "userId": "t20339", "gameId": 2001, "changeType": 3, "betType": 1, "betAmount": 0, "bonus": 50.00, "currency": "BRL", "details": null, "isCompleted": true }

//End game scenario: { "recordId": "682ed6edce1c812d736c4876", "tenantId": 2317, "userId": "t20339", "gameId": 2001, "changeType": 4, "betType": 1, "betAmount": 0, "bonus": 0,

"multiple": 0, "roundId": "12353", "area": 0, "currency": "BRL", "details": null, "isCompleted": true }

//Slot game free spin scenario: { "recordId": "682ed6edce1c812d73ac2899", "tenantId": 2317, "userId": "t20339", "gameId": 2001, "changeType": 0, "betType": 3, "betAmount": 0, "bonus": 0,

"multiple": 0, "roundId": "12353", "area": 0, "currency": "BRL", "details": null, "isCompleted": true, "parentId": "682ed6edce1c812d736c4876" }




## Response Parameters

| Parameter Name      |  Required   |  Type    |  Description  |
| --------   | :----:  | --------   |
| tenantId  |  Yes    | int  | Merchant ID, unique integer assigned by the platform |
| userId  |  Yes    | string  | Merchant's user ID, ID that can distinguish each player |
| balance |  No    | double |  Player balance, regardless of whether deduction is successful or not, should correctly return current account balance and update account balance|
| currency |  No    | string |  Game currency |

 **<font color="red">`Note: Regardless of whether isSuccess is true or false, should correctly return current account balance. The system will update current account balance based on balance value. If current account status is abnormal and cannot play games, balance must return 0`</font>**



> Examples

```json
{
  "isSuccess": true,
  "code": 0,
  "data": {
    "tenantId": 1,
    "userId": "t1_276682",
    "balance": 100000,
    "currency": "BRL"
  }
}
//Insufficient balance scenario:
{
  "isSuccess": false,
  "code": xxx,//Merchant insufficient balance error code, e.g.: 2012
  "message":"Insufficient balance, bet failed",
  "data": {
    "tenantId": 1,
    "userId": "t1_276682",
    "balance": 1.0,    //Current balance
    "currency": "BRL"
  }
}
//Player disabled scenario:
{
  "isSuccess": false,
  "code": xxx,//Merchant status abnormal error code, e.g.: 2013
  "message":"Player disabled, bet failed",
  "data": {
    "tenantId": 1,
    "userId": "t1_276682",
    "balance": 0.0,    //Forced to 0
    "currency": "BRL"
  }
}

betType Bet Type Value List

Value Description
1 Normal bet
2 Chain elimination
3 Free spin
4 Re-spin

changeType Type Description

Value Description
0 Bet and award
1 Normal bet
2 Cancel bet
3 Award prize
4 End game

Game Flow Examples:

For non-direct bet and award scenarios, there will be the following flows:

  1. Normal bet and award Game bet -> Game award (isCompleted=true); corresponding changeType values, from 1 -> 3; Player bets in game, wins and settles, round ends; This applies to most game flows, with the last award having isCompleted=true. This flow is recommended as it reduces one interface call. Game bet -> Game award -> Game round end; corresponding changeType values, from 1 -> 3 -> 4; Player bets in game, wins and settles, round ends; This applies to most game flows;

  2. Cancel bet Game bet -> Cancel bet; corresponding changeType values, 1 -> 2; Player bets in game, voluntarily cancels bet before round starts, generally for multiplayer games, Mini Game type games; Cancel bet recordId is consistent with bet recordId;

  3. No award Game bet -> No win -> Game round end; corresponding changeType values, from 1 -> 4; Player bets in game, doesn't win this round, verifies round end;

  4. One bet multiple awards This situation is generally for chain elimination slot games, slot games entering special gameplay, lottery games. Player bets in game, wins multiple times in this round until round ends. Game bet -> Game award -> Game award -> Game award········ -> Game award (isCompleted=true); corresponding changeType values, from 1 -> 3 -> 3 -> ······· -> 3; Last award has isCompleted=true. This flow is recommended as it reduces one interface call. Game bet -> Game award -> Game award -> Game award········ -> Game round end; corresponding changeType values, from 1 -> 3 -> 3 -> ······· -> 4;

results matching ""

    No results matching ""