Skip to content

Quick Start Example

This page shows a complete freebet lifecycle from award to settlement with full request/response examples.

Complete Flow: Award → Bet → Settle Win

Let's walk through a typical freebet scenario where a player receives a 1000 USD freebet, places a bet with odds 4.0, and wins.

Step 1: Award Freebet

GR8 Tech grants a 1000 USD freebet to the player.

Request:

{
  "currency": "USD",
  "platform": "sport",
  "id": "e09751f8-bf51-48e4-9883-21eaa720920f-a37f67df-4969-4296-a38f-754384128df5",
  "type": "award",
  "initiatedAt": "2024-06-28T13:09:33.000Z",
  "createdAt": "2024-06-28T13:09:33.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "freebet award",
    "sportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "sportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "0.0",
    "bonus": "1000.0", // Freebet amount granted to user
    "locked": "0.0"
  }
}

Your Response:

{
  "currency": "USD",
  "platform": "sport",
  "id": "e09751f8-bf51-48e4-9883-21eaa720920f-a37f67df-4969-4296-a38f-754384128df5",
  "type": "award",
  "initiatedAt": "2024-06-28T13:09:33.000Z",
  "createdAt": "2024-06-28T13:09:33.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "freebet award",
    "sportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "sportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "0.0",
    "bonus": "1000.0",
    "locked": "0.0"
  },
  "balances": {
    "cash": "5000.0",
    "bonus": "1000.0",
    "locked": "0.0",
    "retract": "0.0"
  },
  "alreadyProcessed": false
}

What happened:

  • Player's bonus balance increased by 1000 USD
  • Player now has an active freebet they can use

Step 2: Place Bet

Player places a bet using the freebet. Bet amount: 1000 USD, Odds: 4.0

Request:

{
  "currency": "USD",
  "platform": "sport",
  "id": "0a497028-004d-4b46-b8ba-655757a72474",
  "type": "withdrawal",
  "initiatedAt": "2024-06-28T13:10:31.000Z",
  "createdAt": "2024-06-28T13:10:31.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "freebet",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "sportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "sportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "0.0",
    "bonus": "1000.0", // Freebet amount used for bet
    "locked": "0.0"
  }
}

Your Response:

{
  "currency": "USD",
  "platform": "sport",
  "id": "0a497028-004d-4b46-b8ba-655757a72474",
  "type": "withdrawal",
  "initiatedAt": "2024-06-28T13:10:31.000Z",
  "createdAt": "2024-06-28T13:10:31.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "freebet",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "sportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "sportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "0.0",
    "bonus": "1000.0",
    "locked": "0.0"
  },
  "balances": {
    "cash": "5000.0",
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "0.0"
  },
  "alreadyProcessed": false
}

What happened:

  • Player's bonus balance decreased by 1000 USD
  • Bet is now pending (waiting for event result)
  • Freebet is consumed and cannot be used again

Step 3: Settle Win

The bet wins! Total payout: 1000 × 4.0 = 4000 USD. Player receives: 4000 - 1000 = 3000 USD.

Request:

{
  "currency": "USD",
  "platform": "sport",
  "id": "0a497028-004d-4b46-b8ba-655757a72474_1719581699813782_0",
  "type": "deposit",
  "initiatedAt": "2024-06-28T13:35:00.000Z",
  "createdAt": "2024-06-28T13:35:00.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "settle freebet",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "sportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "sportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "3000.0",
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "1000.0"
  }
}

Your Response:

{
  "currency": "USD",
  "platform": "sport",
  "id": "0a497028-004d-4b46-b8ba-655757a72474_1719581699813782_0",
  "type": "deposit",
  "initiatedAt": "2024-06-28T13:35:00.000Z",
  "createdAt": "2024-06-28T13:35:00.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "settle freebet",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "sportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "sportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "3000.0",
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "1000.0"
  },
  "balances": {
    "cash": "8000.0",
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "1000.0"
  },
  "alreadyProcessed": false
}

What happened:

  • Player's cash balance increased by 3000 USD (winnings excluding freebet amount)
  • Original freebet amount (1000 USD) moved to retract balance
  • Freebet lifecycle is complete

Balance Changes Summary

Step Cash Bonus Retract Description
Initial 5000 0 0 Player's starting balance
After Award 5000 1000 0 Freebet granted
After Bet 5000 0 0 Freebet used for bet
After Settle 8000 0 1000 Winnings paid, freebet to retract

Net result: Player gained 3000 USD cash (profit from the bet).

Key Takeaways

  1. You don't calculate winnings - GR8 Tech sends you the exact amounts in amountBreakdown
  2. Apply amounts as received - Add/subtract values from corresponding balance types
  3. Return updated balances - Always include current balances in your response
  4. Implement idempotency - Same transaction id must return the same response

What's Next?