Change User Balance

The MINI.GAME platform calls this API to modify the player's balance.

This API is only invoked when there is a change in the balance. For example, it is called once when a bet is placed and funds are deducted, once when a payout is made, and once when verification is completed. Each invocation includes a type field that specifies the reason for the call.

ChangeBalance

This API is provided by the integrator and is called by the MINI.GAME platform.

POST {ACCESS_URL}/api/balance/change_balance?trace_id=minigame_trace_id

{ACCESS_URL}is the callback address entered in the integrator's backend.

Headers

Name	Value
Content-Type	"application/json; charset=utf-8"
sign	"minigame_sign_string"

Please refer to the Signature Algorithm and Example page for details on the signature algorithm.

Body

Name	Type	Description
app_id	string	The unique identifier for the user, available in the merchant backend.
player_login_token	string optional	The user token uploaded by the integration partner, the login credential, which is the token verified successfully by the /api/user/verify_session interface.
uname	string	User ID provided by the integrator
currency	string	Currency name, for details, refer to the "name" field of the supported currencies in the currency list.
money	decimal	Balance Change (Positive/Negative)
game_id	integer	Game ID
session_id	string	A unique identifier generated for each game session
order_id	string	A unique identifier generated each time there is a change in the amount (maximum length of 64 characters)
timestamp	integer	timestamp (in seconds)
bet	decimal	Bet Amount: This value is always positive and is only present when the player places a bet.
type	integer	1: Game bet; 2: Cancel bet; 3: In-game payout; 4: End of round payout settlement; See below for type explanation*.
end_round	bool	Is the current game session over
cancel_order_id	string	Value is only available when type=2, indicating which order is being canceled.
award_order_ids	array	This field is only populated when type is 3, representing the total payout amount for all bets in the current round. See details below. award_order_ids Parameter Description*

MINI.GAME Platform Request Parameter Example

{
    "app_id": "10013",
    "bet": 3,
    "game_id": 74,
    "currency":"usdt",
    "money": -3,
    "order_id": "20240716195311drxaoz1mxx6g",
    "player_login_token": "66de94a2-4368-11ef-a0be-581122c6f6d4",
    "session_id": "1813180074526625845",
    "timestamp": 1721130791,
    "uname": "1006417",
    "end_round": false,
    "type": 1,
    "cancel_order_id": "",
    "award_order_ids": null
}

Integrator Response Parameter Example

Success

{
    "data": {
        "balance": "4289.1"
    },
    "code": 1,
    "msg": "ok"
}

Fail

Integrator Response Parameter Example Description

Name	Required	Type	Description
data	Yes	object	Response Data
balance	Yes	decimal	User balance, supports up to 4 decimal places.
code	Yes	integer	Status Code
msg	Yes	string	Prompt message

Error Code

For more error codes, please refer to the General Error Codes page description.

---

*award_order_ids Parameter Description

Type: Array of Objects

The fields of the object are as follows. For more details, please refer to the Game Payout example.

Name	Required	Type	Description
order_id	Yes	string	Bet Order ID
money	Yes	string(decimal)	Payout Amount

*type Parameter Description

Each type corresponds to a separate HTTP call.

• Process Example:

  1. Game Bet → Game rewards and notification of game end.

     • Corresponding type: 1 → 4

     • Description:The player places a bet in the game, with no multiple rewards. After the reward is given, a game round technical verification is performed. This situation applies to most game processes (single reward process).

  2. Game Bet → Cancel Bet.

     • Corresponding type: 1 → 2

     • The player places a bet in the game and voluntarily cancels the bet before the game round starts (mini games cannot cancel the bet autonomously, and when switching between spb-mini games, the bet will be automatically canceled).

  3. Betting in the game → Winning → In-round payouts → In-round payouts → In-round payouts... → Game rewards and notification of game end.

     • Corresponding type: 1 → 3 → 3 → … → 4

Special Note: ①② Generally applies to multiplayer or mini-game types; the session_id for canceling a bet is the same as the session_id for the original bet. ③④ The player places a bet in the game, winning once or multiple times during the round until the game ends; this typically applies to slot games with consecutive eliminations, special bonus rounds in slot games, or lottery-type games.

---

Example Parameters for MINI.GAME ChangeBalance API Request

API Request (Type = 1: User Bet)

{
    "app_id": "10013",
    "bet": "3",
    "game_id": 74,
    "money": "-3",
    "order_id": "20240716195311drxaoz1mxx6g",
    "player_login_token": "66de94a2-4368-11ef-a0be-581122c6f6d4",
    "session_id": "1813180074526625845",
    "timestamp": 1721130791,
    "uname": "1006417",
    "end_round": false,
    "type": 1,
    "cancel_order_id": "",
    "award_order_ids": null
}

API Request (Type = 2: Cancel Bet)

{
    "app_id": "13",
    "player_login_token": "4533126b-f5af-11ee-9a0f-000c2901d9cc",
    "uname": "1033201",
    "money": "10000",
    "game_id": 100001,
    "session_id": "1777333924821798912",
    "order_id": "10920408215323di4cal9or8ji",
    "timestamp": 1712584403,
    "bet": "0",
    "type": 2,
    "end_round": false,
    "cancel_order_id":"20240408215323di4cal9or8jk",
    "award_order_ids":null
}

API Request ( Prize payout during the game round)

{
    "app_id": "10013",
    "bet": "0",
    "game_id": 100001,
    "money": "33.66",
    "order_id": "20240715204114drtuiv8r7ny8",
    "player_login_token": "6049348c-42a7-11ef-a0bd-581122c6f6d4",
    "session_id": "24713",
    "timestamp": 1721047274,
    "uname": "1006415",
    "end_round": false,
    "type": 3,
    "cancel_order_id": "",
    "award_order_ids": [
        {
            "order_id": "20240715204030drtugi3tau4g",
            "money": "5.1"
        },
        {
            "order_id": "20240715204053drtuhqp0jthc",
            "money": "10.2"
        },
        {
            "order_id": "20240715204104drtuibx5hlhc",
            "money": "18.36"
        }
    ]
}

API Request (type=4 Prize settlement and notify the integration party that the game round has ended.）

{
    "app_id": "10013",
    "bet": "0",
    "game_id": 100001,
    "money": "33.66",
    "order_id": "20240715204114drtuiv8r7ny8",
    "player_login_token": "6049348c-42a7-11ef-a0bd-581122c6f6d4",
    "session_id": "24713",
    "timestamp": 1721047274,
    "uname": "1006415",
    "end_round": false,
    "type": 4,
    "cancel_order_id": "",
    "award_order_ids": [
        {
            "order_id": "20240715204030drtugi3tau4g",
            "money": "5.1"
        },
        {
            "order_id": "20240715204053drtuhqp0jthc",
            "money": "10.2"
        },
        {
            "order_id": "20240715204104drtuibx5hlhc",
            "money": "18.36"
        }
    ]
}