A casino bonus engine where nothing is granted before you confirm

How a campaign works

An operator describes a campaign in plain words, for example “50 free spins for everyone who made a second deposit this week”. The bonus module turns it into a plan: audience (a segment), type, amount, wagering multiplier and start time. Nothing is granted at this point. The operator sees a preview with the audience size now, a sample of players, the estimated cost by nominal value and the start time.

1. Plan. The module prepares the campaign and returns a preview that needs confirmation.
2. Confirm. An authorised operator confirms. If the start time is later, the campaign goes to the schedule and runs then.
3. Grant. The kernel, not the module, performs the grant. The audience is recalculated at that moment, because a segment is a rule that stays current.

Rules that do not bend

• One bonus per key. A grant is keyed by campaign and player. Confirming the same plan twice grants nothing the second time.
• Only the kernel writes money. The module never writes to the ledger directly, so there is one place where a bonus can become a balance.
• Wagering is explicit. The multiplier is the number of times the bonus must be turned over in bets before payout. Defaults exist per type and can be overridden per campaign.
• Forfeiture is a first-class action for the player (“Forfeit bonus” in the account) and for the operator, with an event written either way.

What the operator sees afterwards

Each campaign records its audience at execution, its cost and its outcome, and the grant emits events that analytics and the AI read. That is how a bonus is measured: before, intervention, after. See how wagering works for a worked example.

Questions and answers

What bonus types does the engine support?

Free spins and cash bonuses. Each has a wagering multiplier. When it is omitted, the defaults are x20 for cash and x5 for free spins.

Can a bonus be paid without wagering?

Yes, with a multiplier of 0 the bonus goes to the wallet at the moment of the grant. Planning such a campaign requires a separate permission.

Can a bonus be taken back?

A player or an operator can forfeit an active bonus. Wagering progress is lost, the wallet is not touched, the status becomes forfeited, and the action cannot be reversed.

Can the same player receive a campaign bonus twice?

No. Each grant has a key made of the campaign and the player, and the kernel guarantees one bonus per key, so confirming the same plan again grants nothing.