Skip to content

How Bonus Calculations Work

Understanding how GR8 Tech calculates bonus transactions helps you implement the wallet integration correctly.

Key Parameters

Each bonus campaign configured in Journey Builder has two key parameters:

  • Bonus Rate - Determines what portion of bets and winnings are treated as bonus funds (e.g., 0.6 means 60% bonus, 40% cash)
  • Max Bonus Release - Maximum amount of bonus funds that can be converted to cash upon successful wagering

For detailed information about bonus rate calculation, see Sport Bonus Balance documentation.

Bet Placement Logic

When a player places a bet that qualifies for an active bonus campaign, GR8 Tech calculates the amountBreakdown using the following priority:

  1. Bonus funds - Taken proportionally according to bonus rate
  2. Example: Bet amount = 100, bonus rate = 0.6 → 60 taken from bonus balance
  3. Locked funds - Used to cover remaining amount
  4. Cash funds - Used if bonus and locked are insufficient

Example: Player bets 100 with bonus rate 0.6, has 60 bonus and 50 locked:

  • 60 from bonus (100 × 0.6)
  • 40 from locked (remaining amount)
  • 0 from cash (not needed)

Bet Settlement Logic

When a qualifying bet wins, GR8 Tech distributes the payout using the same principle:

  1. Bonus balance - Receives payout proportionally according to bonus rate
  2. Locked balance - Receives payout up to the original locked amount limit
  3. Cash balance - Receives the remaining payout

Example: Payout = 200, bonus rate = 0.6, original locked = 100:

  • 120 to bonus (200 × 0.6)
  • 80 to locked (capped at original 100 limit, so 80 fits)
  • 0 to cash (remaining amount)

Example with locked cap: Payout = 300, bonus rate = 0.6, original locked = 100:

  • 180 to bonus (300 × 0.6)
  • 100 to locked (capped at original locked amount)
  • 20 to cash (remaining amount after locked cap)

Your Responsibility

Important: You don't need to calculate these amounts yourself. GR8 Tech system:

  • Tracks each campaign's bonus and locked balances separately
  • Calculates all amountBreakdown values based on campaign rules
  • Sends you ready-to-apply amounts in each transaction request

Your wallet implementation should:

  • Apply the received amountBreakdown to player balances
  • Return updated balances in the response
  • Implement idempotency to handle duplicate requests

Bet and Settlement Transactions

In addition to the three bonus-specific transaction types (award, release, retract), regular bet and settlement transactions are also affected when a player has an active bonus campaign.

Bonus-Qualified Bets

When a player places a bet that qualifies for an active bonus campaign, you will receive a standard withdrawal transaction with reason: "bet", but it will include bonus-related fields:

Key differences:

  • context.sportBonusOfferId - Identifies which bonus campaign applies to this bet
  • context.sportBonusPlayerOfferId - Identifies the player's specific bonus activation
  • amountBreakdown - Contains bonus, locked, and cash amounts calculated according to bonus rate

Example:

{
  "type": "withdrawal",
  "context": {
    "reason": "bet",
    "betId": "75563c85-01d3-4430-953e-ee061e9e6db3",
    "sportBonusOfferId": "7a3033a4-5b79-48a0-8ae0-f44e953989c1",
    "sportBonusPlayerOfferId": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10"
  },
  "amountBreakdown": {
    "cash": "900.0",
    "locked": "100.0",
    "bonus": "1000.0"
  }
}

Bonus-Qualified Settlements

Similarly, when a bonus-qualified bet is settled, you will receive a standard deposit transaction with reason: "settle" that includes the same bonus-related fields:

Example:

{
  "type": "deposit",
  "context": {
    "reason": "settle",
    "betId": "75563c85-01d3-4430-953e-ee061e9e6db3",
    "sportBonusOfferId": "7a3033a4-5b79-48a0-8ae0-f44e953989c1",
    "sportBonusPlayerOfferId": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10"
  },
  "amountBreakdown": {
    "cash": "1800.0",
    "locked": "200.0",
    "bonus": "2000.0"
  }
}

Your implementation: Handle these transactions the same way as regular bets and settlements - simply apply the amountBreakdown to the player's balances. The presence of sportBonusOfferId and sportBonusPlayerOfferId indicates that this transaction is part of a bonus campaign.

For complete bet and settlement flow examples, see Flow Examples.