Skip to content

Understanding Balance Types

Sport bonus transactions work with four balance types. Understanding each balance is essential for correct implementation.

Cash Balance

The player's real money balance. This is the primary balance used for regular gameplay.

  • Used for placing bets and receiving winnings
  • Can be withdrawn by the player
  • Part of cash may be moved to locked balance during bonus activation

Bonus Balance

The bonus money balance awarded to the player through bonus campaigns.

  • Cannot be withdrawn directly
  • Must be wagered according to campaign requirements
  • Converted to cash upon successful wagering (release transaction)
  • Important: GR8 Tech system maintains separate bonus balances for each active campaign. Bonus funds from different campaigns are not mixed together.

Locked Balance

A portion of the player's real money that is temporarily locked during an active bonus campaign.

Purpose: Locked balance ensures that the player's real money continues to participate in bets alongside bonus funds during the wagering process.

Lifecycle:

  • Moved from cash balance when bonus is awarded
  • Participates in bets together with bonus funds
  • Returned to cash balance when campaign completes (either through successful wagering or cancellation)

Retract Balance

A technical balance that collects bonus funds that were not successfully wagered.

What goes into retract:

  • Bonus funds when campaign is cancelled or wagering requirements are not met
  • Excess bonus funds that exceed the maximum release limit

Implementation note: Maintaining retract balance is optional. You can use it for analytics and reporting purposes, or simply discard these amounts. The retract balance is not available for gameplay or withdrawal.

Balance Structure in Responses

All transaction responses include a nested balance structure:

{
  "balances": {
    "sport": {
      "main": {
        "USD": {
          "cash": "1000.0",
          "bonus": "500.0",
          "locked": "100.0",
          "retract": "0.0"
        }
      },
      "sportsbook": {
        "USD": {
          "cash": "1000.0",
          "bonus": "500.0",
          "locked": "100.0",
          "retract": "0.0"
        }
      }
    }
  }
}

Note: The sport.main and sport.sportsbook balances are typically identical for sport bonus transactions. Both are provided for compatibility with different wallet implementations.