Skip to Content
WalletBonusesFreebetLifecycle & Errors

Freebet Lifecycle and Error Handling

Freebet Lifecycle

Understanding the freebet lifecycle helps you handle edge cases correctly.

Active Freebet Period

A freebet becomes active when:

  • Award transaction is successfully processed
  • Player receives freebet in bonus balance

A freebet is consumed when:

  • Player places a bet using the freebet
  • Bet is settled (win or lose)
  • Freebet amount moves to retract balance

A freebet is cancelled when:

  • Retract transaction is processed (unused freebet removed)
  • Freebet expires without being used

Freebet Usage Rules

One-time use: A freebet can only be used once for a single bet. It cannot be:

  • Split across multiple bets
  • Partially used
  • Reused after settlement

Example: If player has a 1000 freebet, they must use the entire 1000 on one bet.

Multiple Active Freebets

Players can have multiple active freebets simultaneously. Each freebet is identified by:

  • SportBonusOfferId - The freebet campaign identifier
  • SportBonusPlayerOfferId - The player’s specific freebet activation identifier

Your responsibility: If you need to track which bets used which freebet (for analytics or reporting), use these fields to identify specific freebets.

Error Handling

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

Common Freebet-Specific Errors

The most common errors occur when player balances are insufficient:

Insufficient freebet balance:

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

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

Rollback Errors

When processing rollback transactions (type: rollback, reversing a bet placement), you may encounter specific errors.

Parent transaction not found:

{
  "error": {
    "code": "decline.parent.notfound",
    "message": "Original bet transaction not found",
    "origin": "YourCompanyName"
  },
  "alreadyProcessed": false
}

Parent transaction failed:

{
  "error": {
    "code": "decline.parent.failed",
    "message": "Original bet transaction was not successful",
    "origin": "YourCompanyName"
  },
  "alreadyProcessed": false
}

For complete rollback requirements, see Rollback and Retry Logic.

Request Processing Requirements

Note

Transaction Processing Requirements

All freebet transaction requests must be processed following the same requirements as standard wallet transactions:

  • Idempotency: Same transaction id must return the same response (set alreadyProcessed: true for duplicates)
  • Error Handling: Use proper error codes and response structure
  • Retry Logic: Handle retries correctly
  • Rollback Handling: Implement proper rollback logic — rollbacks are retried up to 400 times

For complete details, see PerformTransaction documentation.

Edge Cases

Freebet Bet Placement Rolled Back

If a freebet bet placement cannot be accepted:

  1. You receive a Rollback transaction (reason: rollback freebet, context.parentId = the placement)
  2. Freebet is returned to bonus balance
  3. Player can use it again

Freebet Expires While Bet is Pending

If a freebet expires while a bet is still pending:

  • The bet remains valid
  • Settlement will proceed normally when bet is resolved
  • No retract transaction for the freebet itself (it’s already used)

Multiple Active Freebets

Players can have multiple active freebets simultaneously. Each freebet is a separate entity that the player can choose to use.

How it works:

  • Player may have several freebets available (e.g., 100, 500, 1000)
  • Player selects which freebet to use when placing a bet
  • Each freebet is identified by unique SportBonusOfferId and SportBonusPlayerOfferId
  • Only one freebet can be used per bet

Example: Player has three active freebets:

  • Freebet A: 100 (SportBonusPlayerOfferId: “abc…”)
  • Freebet B: 500 (SportBonusPlayerOfferId: “def…”)
  • Freebet C: 1000 (SportBonusPlayerOfferId: “ghi…”)

When placing a bet, player chooses Freebet B (500). The bet transaction will include:

  • SportBonusPlayerOfferId: "def..."
  • amountBreakdown.bonus: "500.0"

The other freebets (A and C) remain available for future bets.

Balance Tracking

GR8 Tech system tracks all freebet data on our side, including:

  • Active freebets for each player
  • Freebet expiration dates
  • Wagering progress and conditions
  • Which freebet is used for which bet

Your responsibility:

  1. Apply balance changes - Update player balances based on amountBreakdown in each transaction
  2. Return current balances - Include updated balances in your response
  3. Implement idempotency - Store transaction id to detect duplicates

Optional tracking:

If you want to track which bets used which freebet (for analytics or reporting), you can store:

  • SportBonusOfferId - Freebet campaign identifier
  • SportBonusPlayerOfferId - Player’s specific freebet activation identifier
  • Link these to bet transactions using betId

Note: You don’t need to maintain a separate freebet table or track expiration - GR8 Tech handles this and sends appropriate transactions (award, retract) at the right time.

Transaction ReferenceOverview