Get Balance

Get Balance

Info

The Get Balance endpoint retrieves the current balance for a player's account. This is used by games to display the player's up-to-date balance during gameplay.

Overview

The Get Balance method allows game providers to request the current balance for a specific player. This is typically called at various points during gameplay to ensure the player’s displayed balance is accurate. The casino returns both the real money balance and any bonus funds available to the player.

Flow Diagram

sequenceDiagram participant Player participant Game as Game Provider participant Groove as Groove Platform participant Casino as Casino Operator Note over Player,Game: Player views balance in game Game->>Groove: Get Balance Request Groove->>Casino: Forward Get Balance Request Casino->>Casino: Validate Session Casino->>Casino: Retrieve Current Balance Casino->>Groove: Balance Response Groove->>Game: Forward Balance Response Game->>Player: Display Updated Balance

Casino Responsibilities

The casino platform must perform the following operations when processing a Get Balance request:

  1. Session Validation

    • Confirm the incoming game session ID is valid
    • Verify the session is associated with the provided account ID
    • Reject the request if validation fails

  2. Balance Retrieval

    • Retrieve the player’s current real money balance
    • Retrieve the player’s current bonus balance (if applicable)
    • Calculate the total balance (real + bonus)

  3. Response Formatting

    • Return all balance values with consistent decimal precision
    • Include any required CMA-compliance parameters if applicable

Request Details

Endpoint

{casino_endpoint}?request=getbalance&[parameters]

Request Parameters

Parameter Data type Required Description
accountid String(60) - [0-9a-zA-Z] Yes Player’s unique identifier
Example: 5179068
apiversion String Yes API version
Example: 1.2
device String Yes Player’s device type
Valid values: desktop, mobile
gamesessionid String(64) Yes Game session ID
Example: 11_99d71938-c2d9-4844-b950-d598c2es
nogsgameid String Yes Groove game ID
Example: 80102
request String Yes Request method name
Value: getbalance

Example Request

GET {casino_endpoint}?request=getbalance&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&nogsgameid=80102&apiversion=1.2

Response Details

Response Parameters

Parameter Data type Required Description
apiversion String Yes API version
Example: 1.2
balance Decimal (32,10) with max 2 decimal places Yes Total player balance (real + bonus)
Examples: 500.00, 140.25
bonus_balance Decimal (32,10) with max 2 decimal places Yes Player’s bonus balance
Example: 50.00
code Integer Yes Response code (see Appendix)
Example: 200
real_balance Decimal (32,10) with max 2 decimal places Yes Player’s real money balance
Example: 100.00
status String Yes Response status (see Appendix)
Example: Success
game_mode Integer Yes* Game mode:
1 - Real money mode
2 - Bonus mode
*Required for CMA-compliant games
order String Yes* Order type:
cash_money - Real money
bonus_money - Bonus money
*Required for CMA-compliant games
Note

**Note:** The `balance` value must always equal the sum of `real_balance` and `bonus_balance`.

Example Success Response

{
  "code": 200,
  "status": "Success",
  "balance": 100.00,
  "bonus_balance": 50.00,
  "real_balance": 50.00,
  "game_mode": 1,
  "order": "cash_money",
  "apiversion": "1.2"
}

Example Error Response

{
  "code": 1,
  "status": "Technical error",
  "message": "Technical error",
  "apiversion": "1.2"
}

Error Handling

Common Error Codes

Code Status Description
1 Technical error Internal server error
110 Operation not allowed Invalid session or account ID
1000 Not logged on Player session is invalid or expired
Tip

For a complete list of error codes, refer to [Appendix A: Transaction Response Status Codes](/appendix-a-transaction-response-status-codes/).

Implementation Notes

  1. Balance Calculation:

    • The balance value must equal the sum of real_balance and bonus_balance
    • For casinos that don’t use bonus balances, set bonus_balance to 0.00

  2. Frequency of Calls:

    • Games typically call Get Balance after every significant player action
    • Balance may be polled periodically during gameplay
    • Balance should always be refreshed after financial transactions (wagers, results)

  3. Error Handling:

    • If a player’s session has expired, return code 1000 Not logged on
    • This allows the game to prompt the player to log in again if needed

  4. Balance Fields:

    • All balance fields should be returned (balance, bonus_balance, real_balance)

Security

When Signature Validation is enabled:

  1. Include the X-Groove-Signature header in your request
  2. Calculate signature using query parameters (excluding request)
  3. Remember to treat nogsgameid as gameid for sorting purposes
  4. See Signature Validation for detailed implementation

Signature Example

For the request:

GET {casino_endpoint}?request=getbalance&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&nogsgameid=80102&apiversion=1.2

Query parameters for signature (alphabetically sorted, treating nogsgameid as gameid):

  • accountid: “111”
  • apiversion: “1.2”
  • device: “desktop”
  • gameid (from nogsgameid): “80102”
  • gamesessionid: “123_jdhdujdk”

Concatenated values: 1111.2desktop80102123_jdhdujdk

With security key "test_key", the signature would be:

X-Groove-Signature: 434e2b4545299886c8891faadd86593ad8cbf79e5cd20a6755411d1d3822abba
  • Get Account - Retrieves player account information
  • Wager - Updates player balance when placing a bet
  • Result - Updates player balance after a game round completes