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

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

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"
        }
    ]
}

Last updated