Transaction Types Reference¶

This page provides detailed reference for all three bonus-specific transaction types.

Overview¶

Transaction Type	Reason	Type	Description
Bonus Award	`bonus award`	`award`	Grants bonus funds to the user
Bonus Release	`bonus limit release`	`release`	Converts successfully wagered bonus to cash
Bonus Retract	`bonus release`	`retract`	Removes bonus funds when conditions aren't met

1. Award Transaction¶

The award transaction grants bonus funds to the user and locks a portion of their cash balance. This is the first step in the bonus flow.

When it happens:

Award transaction is triggered on activation of Sport Bonus activity

What happens:

Bonus funds are added to the user's bonus balance
A portion of cash balance is moved to locked balance

Award Request Example

{
  "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": "bonus award",
    "sportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "sportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "bonus": "1000.0",  // Bonus amount granted to user
    "locked": "100.0"   // Cash moved from main to locked balance
  }
}

2. Release Transaction¶

The release transaction is triggered when the bonus is successfully wagered. Bonus funds are converted to cash and moved to the main balance.

What happens:

Bonus funds are moved to main balance (up to the bonus limit)
Locked funds are moved to main balance
Any bonus amount exceeding the limit is moved to retract balance

When it happens:

Bonus wagering requirements are met successfully.

Release Request Example

{
  "currency": "USD",
  "platform": "sport",
  "id": "cfaf39ea-89bd-4102-b62b-99e16fac3a75-b00fdb11-7ece-42a1-9be8-97f74bf28bfb-Release",
  "type": "release",
  "initiatedAt": "2024-06-28T13:10:31.000Z",
  "createdAt": "2024-06-28T13:10:31.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "bonus limit release",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "sportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "sportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "bonus": "100.0",    // Bonus moved to main balance
    "locked": "10.0",    // Locked moved to main balance
    "retract": "10.0"    // Excess bonus moved to retract balance
  }
}

3. Retract Transaction¶

The retract transaction is triggered when the bonus conditions are not met. All bonus funds are removed and moved to the retract balance.

What happens:

All bonus funds are moved to retract balance
Locked funds are returned to main balance

When it happens:

Bonus is cancelled, terminated, or wagering requirements are not met.

Retract Request Example

{
  "currency": "USD",
  "platform": "sport",
  "id": "d8f21aca-7938-44cc-becd-7b0afa7ee491-a37f67df-4969-4296-a38f-754384128df5-Retract",
  "type": "retract",
  "initiatedAt": "2024-06-28T13:10:31.000Z",
  "createdAt": "2024-06-28T13:10:31.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "bonus release",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "sportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "sportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "bonus": "1000.0",    // Bonus moved to retract balance
    "locked": "100.0"    // Locked moved to main balance
  }
}

Response Format¶

Transaction Responses

All transaction responses follow the same structure as requests, with the addition of:

balances - Updated player balances after the transaction
alreadyProcessed - Flag indicating if the transaction was already processed (idempotency)

For complete response examples, see Flow Examples.