> For the complete documentation index, see [llms.txt](https://scorpioplay.gitbook.io/scorpio-play-casino-api-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://scorpioplay.gitbook.io/scorpio-play-casino-api-doc/getting-started/bonus-call.md).

# Bonus Call

This page provides an overview of the Bonus Call feature in our API.

{% hint style="info" %}
Please review this page to understand the Bonus Call feature, an essential tool for attracting new players to your casino.
{% endhint %}

### What Is A Bonus Call? <a href="#what-is-a-bonus-call" id="what-is-a-bonus-call"></a>

The Bonus Call feature is crafted to elevate player engagement by allowing temporary bonuses to be added to ongoing games, excluding live games.

This functionality enables agents to offer appealing bonuses to players, thereby enhancing their gaming experience and encouraging continued play.

Crucially, these bonuses are applied in a manner that does not affect the agents' overall points balance, ensuring they can maintain their resources while still providing attractive incentives.

Our platform supports **two types of bonus calls**, allowing operators to reward players and drive engagement through controlled bonus mechanisms.

#### 1. Free Spin Bonus

A **Free Spin Bonus** allows operators to grant a specific number of free spins to a player for a selected game. These spins can be used without deducting funds from the player’s wallet, encouraging players to engage with the game without financial risk.

Key characteristics of Free Spin Bonus:

* A fixed number of spins is assigned to the player
* Spins are tied to a specific game
* Each spin does **not** consume wallet balance
* Wins generated from free spins are automatically credited to the player’s wallet
* Bet amount and spin count are predefined by the operator

This bonus type is typically used for promotions, onboarding campaigns, or re-engagement incentives.

#### 2. Regular Bonus Call

A **Regular Bonus Call** allows operators to grant a **guaranteed winning amount** to a player through **actual gameplay execution**, rather than a direct wallet credit. During this bonus call, the system performs a sequence of spins—either normal spins, bonus rounds, or a combination of both—until the predefined winning amount is achieved.

Unlike Free Spin bonuses, Regular Bonus Calls **use real spin mechanics** and follow the standard game flow.

Key characteristics of Regular Bonus Call

* A predefined **target winning amount** is guaranteed for the player
* The bonus is fulfilled through **randomized gameplay execution**, including:
  * normal spins
  * bonus rounds (if triggered)
* Spin count and spin type are determined dynamically by the game logic
* Each spin **deducts funds from the player’s wallet**, just like a normal paid spin
* The system ensures that the **total winnings meet the guaranteed bonus amount**
* All bet and win transactions are processed and recorded as standard game transactions

How it works (high-level flow)

1. Operator initiates a Regular Bonus Call with a target winning amount.
2. The system executes real spins using the game engine.
3. Bets are deducted from the player’s wallet for each spin.
4. Wins from spins and/or bonus rounds are credited normally.
5. The process continues until the guaranteed winning amount is reached.

Typical use cases

* Guaranteed win promotions
* Player retention campaigns with controlled payout
* Compensation scenarios where winnings must follow normal RTP behavior
* Promotional events requiring real gameplay interaction

#### Difference between Free Spin Bonus and Regular Bonus Call

| Feature             | Free Spin Bonus           | Regular Bonus Call          |
| ------------------- | ------------------------- | --------------------------- |
| Wallet balance used | No                        | Yes                         |
| Guaranteed outcome  | No (win depends on spins) | Yes (target win amount)     |
| Gameplay execution  | Yes                       | Yes                         |
| Spin type           | Free spins only           | Normal spins & bonus rounds |
| Bet deducted        | No                        | Yes                         |
| Operator control    | Spin count                | Target win amount           |

### How To Use Bonus Call Feature

To initiate a bonus call, use the **`POST /v1/bonus-call/register`** endpoint. When registering a bonus call, you must specify the **bonus call type**, such as *Free Spin Bonus* or *Regular Bonus Call*, along with the required parameters for that bonus.

Once a bonus call is registered, it becomes active for the player. While the bonus call is still in progress and has not been completed, it can be canceled using the **`POST /v1/bonus-call/cancel`** endpoint.

#### Bonus Call Lifecycle Rules

* **Free Spin Bonus**
  * Free Spin Bonuses have a predefined **expiration time**.
  * If the bonus is not fully used before the expiration time, it will be **automatically expired** by the system.
  * Any unused free spins after expiration are forfeited.
* **Regular Bonus Call**
  * The bonus remains active until the **specified winning amount** has been fully delivered to the player through gameplay or the expiration time.
  * The bonus must either be completed or manually canceled.

This design allows operators to run both time-limited promotional bonuses and long-running guaranteed-win bonuses with full control over their lifecycle.