Sport Bonus Amount Flow Examples¶

This page contains detailed examples of two main bonus flow scenarios.

More specific flows and examples for working with balances are described in the Sport Bonus Balance documentation.

Available Examples¶

Complete Flow: Successful Bonus Release
Alternative Flow: Bonus Retract

Complete Flow: Successful Bonus Release¶

Scenario: User receives a bonus, places a winning bet, and successfully completes wagering requirements. The bonus is released, but exceeds the maximum release limit.

Disabling locking balance

Disabling locking cash balance is allowed per brand. If you want to disable locking cash balance, please contact with AM/PM of GR8 TECH team.

Key parameters:

Initial cash balance: 1000 USD
Bonus amount: 1000 USD
Locked amount: 100 USD
Max bonus release: 1700 USD
Bonus rate: 0.5 (50%)

Initial State (Before Bonus)¶

The user has the following balances:

User's Initial Balances

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

Step 1: Bonus Award¶

The bonus is awarded to the user.

Configuration:

maxBonusRelease = 1700
bonusRate = 0.5

Balance changes:

Cash: 1000 → 900 (-100 moved to locked)
Bonus: 0 → 1000 (+1000 awarded)
Locked: 0 → 100 (+100 from cash)

Bonus Award Request

{
  "id": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10-7a3033a4-5b79-48a0-8ae0-f44e953989c1-0",
  "currency": "USD",
  "platform": "sport",
  "type": "award",
  "createdAt": "2025-07-11T07:30:50Z",
  "initiatedAt": "2025-07-11T07:30:50Z",
  "context": {
    "product": "sportsbook",
    "reason": "bonus award",
    "SportBonusOfferId": "7a3033a4-5b79-48a0-8ae0-f44e953989c1",
    "SportBonusPlayerOfferId": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10"
  },
  "amountBreakdown": {
    "locked": "100.0",
    "bonus": "1000.0"
  }
}

Bonus Award Response

{
  "balances": {
    "sport": {
      "main": {
        "USD": {
          "cash": "900.0",
          "bonus": "1000.0",
          "locked": "100.0",
          "retract": "0.0"
        }
      },
      "sportsbook": {
        "USD": {
          "cash": "900.0",
          "bonus": "1000.0",
          "locked": "100.0",
          "retract": "0.0"
        }
      }
    }
  },
  "alreadyProcessed": false,
  "currency": "USD",
  "platform": "sport",
  "id": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10-7a3033a4-5b79-48a0-8ae0-f44e953989c1-0",
  "type": "award",
  "initiatedAt": "2025-07-11T07:30:50.000Z",
  "createdAt": "2025-07-11T07:30:50.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "bonus award",
    "SportBonusOfferId": "7a3033a4-5b79-48a0-8ae0-f44e953989c1",
    "SportBonusPlayerOfferId": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10"
  },
  "amountBreakdown": {
    "locked": "100.0",
    "bonus": "1000.0"
  }
}

Step 2: Bet Placement and Settlement¶

User places a bet using bonus funds and wins.

Bet parameters:

Bet amount: 2000 USD
Odds: 2.0
Expected payout: 4000 USD

Bet Placement¶

Balance changes:

Cash: 900 → 0 (-900 used for bet)
Bonus: 1000 → 0 (-1000 used for bet)
Locked: 100 → 0 (-100 used for bet)

Place Bet Request

{
  "id": "75563c85-01d3-4430-953e-ee061e9e6db3",
  "currency": "USD",
  "platform": "sport",
  "type": "withdrawal",
  "createdAt": "2025-07-11T07:32:21Z",
  "initiatedAt": "2025-07-11T07:32:21Z",
  "context": {
    "product": "sportsbook",
    "reason": "bet",
    "betId": "75563c85-01d3-4430-953e-ee061e9e6db3",
    "SportBonusOfferId": "7a3033a4-5b79-48a0-8ae0-f44e953989c1",
    "SportBonusPlayerOfferId": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10"
  },
  "amountBreakdown": {
    "cash": "900.0",    // Remaining bet amount after bonus and locked (2000 - 1000 - 100)
    "locked": "100.0",  // All available locked balance used
    "bonus": "1000.0"   // Bonus portion: bet amount × bonus rate (2000 × 0.5)
  }
}

Place Bet Response

{
  "balances": {
    "sport": {
      "main": {
        "USD": {
          "cash": "0.0",
          "bonus": "0.0",
          "locked": "0.0",
          "retract": "0.0"
        }
      },
      "sportsbook": {
        "USD": {
          "cash": "0.0",
          "bonus": "0.0",
          "locked": "0.0",
          "retract": "0.0"
        }
      }
    }
  },
  "alreadyProcessed": false,
  "currency": "USD",
  "platform": "sport",
  "id": "75563c85-01d3-4430-953e-ee061e9e6db3",
  "type": "withdrawal",
  "initiatedAt": "2025-07-11T07:32:21.000Z",
  "createdAt": "2025-07-11T07:32:21.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "bet",
    "betId": "75563c85-01d3-4430-953e-ee061e9e6db3",
    "SportBonusOfferId": "7a3033a4-5b79-48a0-8ae0-f44e953989c1",
    "SportBonusPlayerOfferId": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10"
  },
  "amountBreakdown": {
    "cash": "900.0",
    "bonus": "1000.0",
    "locked": "100.0"
  }
}

Bet Settlement (Win)¶

Calculation:

Payout: 4000 USD
Bonus portion: 4000 × 0.5 (bonus rate) = 2000 USD
Remaining after bonus: 4000 - 2000 = 2000 USD
Locked portion: 200 USD (distributed from remaining, up to original locked limit)
Cash portion: 1800 USD (remaining after bonus and locked)

Balance changes:

Cash: 0 → 1800 (+1800 from winnings)
Bonus: 0 → 2000 (+2000 bonus winnings)
Locked: 0 → 200 (+200 from winnings)

Settle Request

{
  "id": "75563c85-01d3-4430-953e-ee061e9e6db3_1752219153695716_0",
  "currency": "USD",
  "platform": "sport",
  "type": "deposit",
  "createdAt": "2025-07-11T07:32:34Z",
  "initiatedAt": "2025-07-11T07:32:34Z",
  "context": {
    "product": "sportsbook",
    "reason": "settle",
    "betId": "75563c85-01d3-4430-953e-ee061e9e6db3",
    "SportBonusOfferId": "7a3033a4-5b79-48a0-8ae0-f44e953989c1",
    "SportBonusPlayerOfferId": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10"
  },
  "amountBreakdown": {
    "cash": "1800.0",    // Cash portion of winnings
    "locked": "200.0",   // Locked portion (up to original locked limit)
    "bonus": "2000.0",   // Bonus portion: payout × bonus rate (4000 × 0.5)
    "retract": "0.0"
  }
}

Settle Response

{
  "balances": {
    "sport": {
      "main": {
        "USD": {
          "cash": "1800.0",
          "locked": "200.0",
          "bonus": "2000.0",
          "retract": "0.0"
        }
      },
      "sportsbook": {
        "USD": {
          "cash": "1800.0",
          "locked": "200.0",
          "bonus": "2000.0",
          "retract": "0.0"
        }
      }
    }
  },
  "alreadyProcessed": false,
  "currency": "USD",
  "platform": "sport",
  "id": "75563c85-01d3-4430-953e-ee061e9e6db3_1752219153695716_0",
  "type": "deposit",
  "initiatedAt": "2025-07-11T07:32:34.000Z",
  "createdAt": "2025-07-11T07:32:34.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "settle",
    "betId": "75563c85-01d3-4430-953e-ee061e9e6db3",
    "SportBonusOfferId": "7a3033a4-5b79-48a0-8ae0-f44e953989c1",
    "SportBonusPlayerOfferId": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10"
  },
  "amountBreakdown": {
    "cash": "1800.0",    // Cash portion of winnings
    "locked": "200.0",   // Locked portion (up to original locked limit)
    "bonus": "2000.0",   // Bonus portion: payout × bonus rate (4000 × 0.5)
    "retract": "0.0"
  }
}

Step 3: Bonus Release¶

Wagering requirements are met. The bonus is released, but the amount (2000) exceeds the maximum release limit (1700).

Release calculation:

Total bonus available: 2000 USD
Max bonus release: 1700 USD
Released to cash: 1700 USD
Excess moved to retract: 300 USD

Balance changes:

Cash: 1800 → 3700 (+1700 from bonus release, +200 from locked)
Bonus: 2000 → 0 (-2000 released)
Locked: 200 → 0 (-200 released to cash)
Retract: 0 → 300 (+300 excess bonus)

Final result: User ends with 3700 USD cash (started with 1000 USD, net gain: 2700 USD)

Bonus Release Request

{
  "id": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10-7a3033a4-5b79-48a0-8ae0-f44e953989c1-Release",
  "currency": "USD",
  "platform": "sport",
  "type": "release",
  "createdAt": "2025-07-11T07:32:34Z",
  "initiatedAt": "2025-07-11T07:32:34Z",
  "context": {
    "product": "sportsbook",
    "reason": "bonus limit release",
    "SportBonusOfferId": "7a3033a4-5b79-48a0-8ae0-f44e953989c1",
    "SportBonusPlayerOfferId": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10"
  },
  "amountBreakdown": {
    "locked": "200.0",   // All locked funds returned to cash balance
    "bonus": "1700.0",   // Bonus converted to cash (capped at maxBonusRelease limit)
    "retract": "300.00"  // Excess bonus beyond limit (2000 - 1700) moved to retract
  }
}

Bonus Release Response

{
  "balances": {
    "sport": {
      "main": {
        "USD": {
          "cash": "3700.0",
          "locked": "0.0",
          "bonus": "0.0",
          "retract": "300.0"
        }
      },
      "sportsbook": {
        "USD": {
          "cash": "3700.0",
          "locked": "0.0",
          "bonus": "0.0",
          "retract": "300.0"
        }
      }
    }
  },
  "alreadyProcessed": false,
  "currency": "USD",
  "platform": "sport",
  "id": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10-7a3033a4-5b79-48a0-8ae0-f44e953989c1-Release",
  "type": "release",
  "initiatedAt": "2025-07-11T07:32:34.000Z",
  "createdAt": "2025-07-11T07:32:34.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "bonus limit release",
    "SportBonusOfferId": "7a3033a4-5b79-48a0-8ae0-f44e953989c1",
    "SportBonusPlayerOfferId": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10"
  },
  "amountBreakdown": {
    "locked": "200.0",   // All locked funds returned to cash balance
    "bonus": "1700.0",   // Bonus converted to cash (capped at maxBonusRelease limit)
    "retract": "300.00"  // Excess bonus beyond limit (2000 - 1700) moved to retract
  }
}

Alternative Flow: Bonus Retract¶

Scenario: User receives a bonus but fails to meet wagering requirements, or the bonus is cancelled/terminated. All bonus funds are removed.

Initial State (After Bonus Award)¶

User has received a bonus and has the following balances:

User's Balances Before Retract

{
  "sport": {
    "main": {
      "USD": {
        "cash": "900.0",
        "bonus": "1000.0",
        "locked": "100.0",
        "retract": "0.0"
      }
    }
  }
}

Bonus Retract¶

What happens:

All bonus funds are removed and moved to retract balance
Locked funds are returned to main cash balance

Balance changes:

Cash: 900 → 1000 (+100 from locked returned)
Bonus: 1000 → 0 (-1000 removed)
Locked: 100 → 0 (-100 returned to cash)
Retract: 0 → 1000 (+1000 bonus removed)

Final result: User returns to original 1000 USD cash balance (no net gain/loss)

Retract Request

{
  "id": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10-7a3033a4-5b79-48a0-8ae0-f44e953989c1-Retract",
  "currency": "USD",
  "platform": "sport",
  "type": "retract",
  "createdAt": "2025-07-11T13:02:45Z",
  "initiatedAt": "2025-07-11T13:02:45Z",
  "context": {
    "product": "sportsbook",
    "reason": "bonus release",
    "SportBonusOfferId": "7a3033a4-5b79-48a0-8ae0-f44e953989c1",
    "SportBonusPlayerOfferId": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10"
  },
  "amountBreakdown": {
    "locked": "100.0",  // Locked funds returned to cash balance
    "bonus": "1000.0"   // All bonus funds moved to retract (not wagered)
  }
}

Retract Response

{
  "balances": {
    "sport": {
      "main": {
        "USD": {
          "cash": "1000.0",
          "locked": "0.0",
          "bonus": "0.0",
          "retract": "1000.0"
        }
      },
      "sportsbook": {
        "USD": {
          "cash": "1000.0",
          "locked": "0.0",
          "bonus": "0.0",
          "retract": "1000.0"
        }
      }
    }
  },
  "alreadyProcessed": false,
  "currency": "USD",
  "platform": "sport",
  "id": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10-7a3033a4-5b79-48a0-8ae0-f44e953989c1-Retract",
  "type": "retract",
  "initiatedAt": "2025-07-11T13:02:45.000Z",
  "createdAt": "2025-07-11T13:02:45.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "bonus release",
    "SportBonusOfferId": "7a3033a4-5b79-48a0-8ae0-f44e953989c1",
    "SportBonusPlayerOfferId": "2b022fd3-6997-4e89-b4dd-e27fffdf1c10"
  },
  "amountBreakdown": {
    "locked": "100.0",  // Locked funds returned to cash balance
    "bonus": "1000.0"   // All bonus funds moved to retract (not wagered)
  }
}