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 needs to be cancelled, the freebet is returned to the user.

What happens:

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

Rollback Processing Requirements

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

Verify parent transaction exists using context.parentId
Return appropriate error codes (decline.parent.notfound, decline.parent.failed)
Subject to infinite retry logic until 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.

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.