Freebet Transaction Reference

This page provides detailed reference for core freebet transactions.

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

Note: All transaction types are required for complete freebet integration.

1. Freebet Award

The first step is to award the freebet to the user.

What happens:

Freebet amount is added to bonus balance
Player can now use this freebet to place a bet

Freebet Award 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"
  }
}

Freebet Award 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
}

2. Place Bet

User places a bet using the freebet.

What happens:

Freebet amount is deducted from bonus balance
No cash is deducted (it’s a free bet!)

Place Bet 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"
  }
}

Place Bet 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
}

3. Rollback Bet

If the bet placement could not be accepted, the freebet is returned to the user. As with regular bets, rollback freebet reverses a placement only.

What happens:

Freebet amount is returned to bonus balance
Player can use it again

Note

Rollback Processing Requirements

Freebet rollback transactions must follow the same processing requirements as standard rollbacks:

Verify parent transaction exists using context.parentId — the parent is always the freebet placement
Return appropriate error codes (decline.parent.notfound, decline.parent.failed)
Retried every 5 minutes for up to 400 attempts until a definitive response

For complete rollback requirements and retry behavior, see Rollback and Retry Logic.

Rollback Bet Request


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

Rollback Bet Response


{
  "currency": "USD",
  "platform": "sport",
  "id": "0a497028-004d-4b46-b8ba-655757a72474-rollback",
  "type": "rollback",
  "initiatedAt": "2024-06-28T13:10:31.000Z",
  "createdAt": "2024-06-28T13:10:31.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "rollback freebet",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "SportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "SportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f",
    "parentId": "0a497028-004d-4b46-b8ba-655757a72474"
  },
  "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
}

4. Settle Win

When the bet wins, the user receives winnings (excluding the original freebet amount).

What happens:

Cash balance receives winnings (payout - freebet amount)
Original freebet amount moves to retract balance

Example calculation:

Freebet: 1000, Odds: 4.0
Total payout: 1000 × 4.0 = 4000
Cash winnings: 4000 - 1000 = 3000
Retract: 1000 (original freebet)

Settle Win 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",     // Winnings (payout - freebet amount)
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "1000.0"   // Original freebet amount
  }
}

Settle Win 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
}

5. Settle Lose

When the bet loses, no payout is made.

What happens:

No cash is added (bet lost)
Original freebet amount moves to retract balance

Settle Lose Request


{
  "currency": "USD",
  "platform": "sport",
  "id": "0a497028-004d-4b46-b8ba-655757a72474_1719581718177509_0",
  "type": "deposit",
  "initiatedAt": "2024-06-28T13:35:18.000Z",
  "createdAt": "2024-06-28T13:35:18.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": "0.0",        // No winnings (bet lost)
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "1000.0"   // Original freebet amount
  }
}

6. Cancel Settle

Reverts a previous settlement when the bet result needs to be corrected. After cancel settle, the bet returns to unsettled state.

What happens:

Previous settlement is reversed
Cash winnings are taken back (if it was a win)
Freebet amount returns from retract balance
Bet is now in unsettled state (waiting for new settlement)

When it happens:

Bet result was completely incorrect and needs to be changed
Event is cancelled or postponed after settlement
Manual correction is needed by operators

Important: After cancel settle, you will receive a new Settle transaction with the corrected result.

Important

Cancel settle is not a rollback, even though it is often called one. It is a withdrawal with reason cancelsettle freebet.

Cancel Settle Request


{
  "currency": "USD",
  "platform": "sport",
  "id": "0a497028-004d-4b46-b8ba-655757a72474_1719581706873613_0",
  "type": "withdrawal",
  "initiatedAt": "2024-06-28T13:35:07.000Z",
  "createdAt": "2024-06-28T13:35:07.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "cancelsettle freebet",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "SportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "SportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "3000.0",     // Winnings taken back (if was a win)
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "1000.0"   // Freebet returns from retract
  }
}

7. Resettle

Applies a corrected bet result without cancelling the previous settlement. Used for direct adjustments.

What happens:

Payout is adjusted directly (no unsettled state)
Can be deposit (adding funds) or withdrawal (removing funds)
Cash winnings added or removed based on correction
Retract balance is not affected (freebet already consumed)

When it happens:

Bet result needs adjustment (e.g., odds changed, partial correction)
Direct payout correction without full cancellation
Manual adjustment by operators

Key difference from Cancel Settle: Resettle adjusts the result directly without returning bet to unsettled state. Cancel Settle completely reverts settlement, then a new Settle transaction follows.

Resettle Win Request (deposit)


{
  "currency": "USD",
  "platform": "sport",
  "id": "0a497028-004d-4b46-b8ba-655757a72474_1719822877083933_0",
  "type": "deposit",
  "initiatedAt": "2024-07-01T08:34:37.000Z",
  "createdAt": "2024-07-01T08:34:37.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "resettle freebet",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "SportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "SportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "3000.0",     // Winnings added (if win)
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "0.0"   // Freebet already in retract
  }
}

Resettle Loss Request (withdrawal)


{
  "currency": "USD",
  "platform": "sport",
  "id": "0a497028-004d-4b46-b8ba-655757a72474_1719581726333059_0",
  "type": "withdrawal",
  "initiatedAt": "2024-06-28T13:35:26.000Z",
  "createdAt": "2024-06-28T13:35:26.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "resettle freebet",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "SportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "SportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "3000.0",      // Amount to remove (payout adjustment)
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "0.0"      // Freebet already in retract
  }
}

8. Retract (Cancel Unused Freebet)

This transaction removes an unused freebet from the user’s account.

What happens:

Freebet is removed from bonus balance
Moved to retract balance

When it happens:

Freebet expires
Freebet campaign is cancelled
Player doesn’t use the freebet within the allowed timeframe

Retract Request


{
  "currency": "USD",
  "platform": "sport",
  "id": "d8f21aca-7938-44cc-becd-7b0afa7ee491-a37f67df-4969-4296-a38f-754384128df5-Retract",
  "type": "retract",
  "initiatedAt": "2024-07-02T09:03:51.000Z",
  "createdAt": "2024-07-02T09:03:51.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "freebet release",
    "SportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "SportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "0.0",
    "bonus": "1000.0"  // Freebet removed from bonus balance
  }
}

Response Format

All transaction responses must include:

All fields from the request (mirror back)
balances - Updated player balances after applying the transaction
alreadyProcessed - Set to true if this transaction was already processed (idempotency)

Example response structure:


{
  // ... all request fields ...
  "balances": {
    "cash": "8000.0",
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "1000.0"
  },
  "alreadyProcessed": false
}

Important notes:

Response must be identical for duplicate requests (same transaction id)
All balance values must be strings with decimal format (e.g., “1000.0”)
Include all four balance types even if some are zero

For complete response requirements, see PerformTransaction documentation.