Freespins Overview

Freespins let you give a player a number of free rounds, at a fixed bet, in one or more games. Beexar plays them without touching the player’s wallet, and when the issue is over it reports once what the free rounds won, for you to credit.

The API follows the SoftSwiss Game Aggregator Freespins API one to one: three calls you make — Bet/Levels, Freespins/Issue and Freespins/Cancel — and one callback you answer, Freespins/Finish.

---

The Flow

sequenceDiagram
    participant Operator
    participant Beexar
    participant Player

    Operator->>Beexar: POST /api/v1/softswiss/bet/levels
    Beexar-->>Operator: { bet_levels }
    Note over Operator: record the issue in your ledger
    Operator->>Beexar: POST /api/v1/softswiss/freespins/issue
    Beexar-->>Operator: {}
    Operator->>Beexar: POST /api/v1/softswiss/launcher/real (as usual)
    Beexar-->>Operator: { launch_url }
    Player->>Beexar: plays the free rounds, bet locked
    Note over Beexar: free rounds send no /betwin and no /finish
    Beexar->>Operator: POST {freespins_finish_url} { issue_id, amount }
    Operator-->>Beexar: { balance }

1. Bet levels. Bet/Levels lists, per game and currency, the levels a freespin can be issued at. A level is the total bet of one round.
2. Issue. Record the issue in your own ledger, then send Freespins/Issue: freespins_quantity free rounds at bet_level in games, for one player, until valid_until.
3. Launch. The player launches one of the games with a normal real-money launch — nothing new in the request. Beexar finds the player’s freespins and opens the game in freespins mode.
4. Play. Each round costs one free spin. Your wallet sees nothing: no /betwin, no /finish, no balance change.
5. Finish. When every free round has been played, or the issue expires after at least one was played, Beexar sends Freespins/Finish with the total won. You credit it and answer the new balance.

Freespins/Cancel can come at any point, even while the player is playing. A canceled issue never reaches Finish: what it won is forfeited.

---

Enabling Freespins for an Operator

The result of an issue is sent to a fifth callback URL, separate from the four round callbacks: Freespins finish URL on the operator’s Callback URLs tab in the backoffice (see API Keys & Callbacks). A Beexar platform administrator sets it: your organization sees the field read-only, and a change to it from your side is refused (403). To enable freespins, or to change the URL, contact your Beexar account manager.

Freespins finish URL	Result
Set	The operator can issue freespins
Empty	Freespins/Issue answers api_code 406. Bet levels, launches and the four callbacks work as before

Tip

With the official SDKs, end the URL in /freespins/finish — for example https://casino.example.com/wallet/freespins/finish. They route on the path suffix, longest route first, so it can share a prefix with /finish.

---

Issue Lifecycle

From	To	When	Finish sent?
active	finished	Every free round has been played	Yes — the total won
active	finished	valid_until passed after at least one round was played	Yes — what the played rounds won
active	expired	valid_until passed and no round was played	No
active	canceled	Freespins/Cancel	No — the winnings are forfeited

A round already playing when the issue expires or is canceled is played to the end. An issue that expires finishes only after that round closes, so its result includes it.

---

What the Player Sees

• The game opens in freespins mode: the bet amount is locked at the issue’s bet and the remaining count is shown large on the game field itself, for example “FREE SPINS 7 / 10”, together with the amount won so far.
• Choices inside the game stay with the player — the target in dice, the risk in plinko, the cash-out in crash.
• In Candy Cash a freespin is a Classic drop: bonus buys are not offered, and everything the drop wins, the chest included, counts toward the issue.
• In Mine Cash a freespin is a base round, played to a cash out as usual: Bonus Buy is not offered, and the win counts toward the issue.
• When the issue ends, a summary shows the total won, and whether it will be paid (a canceled issue’s is not).
• A player with several issues for one game plays the one that expires first.

---

Which Games

Bet/Levels lists exactly the games that play operator freespins. Freespins/Issue for any other game answers api_code 608 (the game plays no freespins) or 405 (your casino does not have the game). Name games by their slug (dice), without a provider prefix: Beexar is the provider.

The has_freespins flag in the games list is a different thing: it marks a game with its own in-game free spins, not a game that plays operator freespins.

---

SDKs

All four official SDKs support freespins from version 1.2.0: the client issues and cancels them and reads the bet levels, and the wallet server takes an optional fifth handler method for Freespins/Finish. A wallet that does not offer freespins needs no change.