Skip to content

Freebet

Overview

Freebet allows players to place bet without using their own funds. If the bet wins, the player receives the winnings (excluding the original freebet amount). If the bet loses, no funds are deducted from the player's balance.

Key characteristics:

  • No wagering requirements
  • Winnings paid as cash (freebet amount excluded)
  • One-time use per freebet

Quick Start

To integrate freebet, you need to:

  1. Understand how freebet works - Learn the mechanics and balance types
  2. Implement core transactions - Award, Bet, Settle, Retract
  3. Follow lifecycle rules - One-time use, multiple freebets support

New to freebets? Start with the Quick Start Example to see a complete flow with request/response examples.

Core Transaction Types

Transaction Type Reason Type Description
Freebet Award freebet award award Grants freebet to user
Place Bet freebet withdrawal User places bet using freebet
Rollback Bet rollback freebet rollback Cancels bet and returns freebet
Settle settle freebet deposit Freebet settlement (win/lose/return)
Cancel Settle cancelsettle freebet withdrawal Reverts settlement
Resettle (positive) resettle freebet deposit Adjust settlement with additional payout
Resettle (negative) resettle freebet withdrawal Adjust settlement by taking back funds
Retract freebet release retract Removes unused freebet

See: Transaction Reference for detailed examples.

Documentation Structure

This guide is organized into the following sections:

Quick Start Example

Complete freebet lifecycle with full request/response examples:

  • Award → Place Bet → Settle Win flow
  • Balance changes at each step
  • What you need to implement

Flow Diagrams

Visual sequence diagrams for all freebet scenarios:

  • Basic flows (award, bet, settle)
  • Rollback and corrections
  • Multiple active freebets
  • Cancel Settle vs Resettle comparison

How Freebet Works

Understand the freebet mechanics:

  • Balance types used (bonus, cash, retract)
  • Freebet lifecycle (award → bet → settle)
  • Winnings calculation (payout - freebet amount)
  • Multiple active freebets support

Transaction Reference

Detailed reference for all freebet transactions:

  • Freebet Award - Grant freebet to player
  • Place Bet - Player uses freebet
  • Rollback Bet - Cancel bet and return freebet
  • Settle Win/Lose - Bet settlement
  • Cancel Settle - Revert previous settlement
  • Resettle - Apply corrected result
  • Retract - Remove unused freebet

Includes complete request/response examples with field descriptions.

Lifecycle and Error Handling

Learn about freebet lifecycle and error handling:

  • Active freebet period
  • One-time use rules
  • Multiple active freebets
  • Common error scenarios
  • Request processing requirements

Key Concepts

Winnings Calculation

The key concept: Player receives winnings minus the original freebet amount.

Example:

  • Freebet: 1000, Odds: 4.0
  • Total payout: 1000 × 4.0 = 4000
  • Player receives: 4000 - 1000 = 3000 (cash)
  • Original freebet: 1000 (moved to retract)

GR8 Tech Handles Calculations

You don't need to calculate winnings yourself. GR8 Tech system:

  • Tracks freebet balances for each campaign
  • Calculates all amountBreakdown values
  • Sends you ready-to-apply amounts in each transaction request

Your responsibility: Apply the received amountBreakdown to player balances and return updated balances.

One-Time Use

Each freebet can only be used once for a single bet. It cannot be:

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

Idempotency Required

All freebet transactions must follow the same idempotency requirements as standard wallet transactions. See PerformTransaction documentation for complete details.

Next Steps

  1. Start with Quick Start Example to see a complete flow
  2. Review Flow Diagrams for visual understanding
  3. Read How Freebet Works to understand the mechanics
  4. Implement using Transaction Reference
  5. Handle edge cases with Lifecycle and Error Handling

Additional Resources