Bonus Lifecycle and Error Handling¶

Bonus Lifecycle¶

Understanding the bonus lifecycle helps you handle edge cases correctly.

Active Bonus Period¶

A bonus campaign becomes active when:

• Award transaction is successfully processed
• Player receives bonus and locked balances

A bonus campaign ends when:

• Release transaction is processed (successful wagering)
• Retract transaction is processed (cancelled or failed wagering)

Important: Post-Completion Settlements¶

Even after a bonus campaign ends (release or retract), you may still receive settlement transactions for bets that were placed during the active period but not yet settled.

Example scenario:

1. Player places bet with bonus funds
2. Bonus campaign completes (release/retract)
3. Later, the bet is settled → you receive settlement transaction with sportBonusOfferId and sportBonusPlayerOfferId

Your wallet must handle these late settlements correctly by applying the amountBreakdown as usual.

Multiple Active Bonuses¶

Players can have multiple active bonus campaigns simultaneously. GR8 Tech system:

• Tracks separate bonus and locked balances for each campaign
• Sends transactions with unique sportBonusOfferId and sportBonusPlayerOfferId combinations
• Calculates amountBreakdown independently for each campaign

Your responsibility: If you need to track which bets were applied to which bonus campaign (for analytics or reporting), use the sportBonusOfferId and sportBonusPlayerOfferId fields to identify specific campaigns.

Error Handling¶

Bonus transactions follow the same error handling requirements as standard wallet transactions. See PerformTransaction Error Responses for complete details.

Common Bonus-Specific Errors¶

The most common errors occur when player balances are insufficient:

Insufficient bonus balance:

{
  "error": {
    "code": "decline.lowbalance",
    "message": "Insufficient bonus balance",
    "origin": "YourCompanyName"
  },
  "alreadyProcessed": false
}

Insufficient locked balance:

{
  "error": {
    "code": "decline.lowbalance",
    "message": "Insufficient locked balance",
    "origin": "YourCompanyName"
  },
  "alreadyProcessed": false
}

Insufficient cash balance:

{
  "error": {
    "code": "decline.lowbalance",
    "message": "Insufficient cash balance",
    "origin": "YourCompanyName"
  },
  "alreadyProcessed": false
}

Best practice: Include specific balance type in the error message to help with debugging.

Request Processing Requirements¶