Bonuses Guide

Wagering bonuses with playthrough requirements. Users receive a bonus amount and must wager a multiple of it before it's unlocked.

Works standalone - no challenge or funded account required.

---

How It Works

1. Operator creates bonus offers in the backoffice
2. Users activate a bonus (or it's granted automatically/manually)
3. Every qualifying bet contributes stake toward the wagering target
4. On completion (target met), bonus.completed webhook fires
5. If user withdraws from sportsbook and offer has forfeitOnWithdrawal, bonus is forfeited

---

Deployment Modes

Mode	Description
Challenges + Bonuses	Bonus wagering runs alongside challenge progress
Bonuses only	Pure wagering bonuses. Decoupled from challenges entirely.

---

Bonus Offer Fields

Field	Required	Description
name	Yes	Display name ("Welcome 100% Match")
bonusType	Yes	deposit_match, free_bet, no_deposit, cashback, reload
matchPercent	For match types	Match percentage (100 = 100% match)
maxBonusAmount	Yes	Max bonus in cents (e.g. 5000 = 50 EUR)
wageringMultiplier	Yes	Times to wager (e.g. 8 = 8x bonus amount)
minOdds	No	Minimum odds for qualifying bets (default: 1.50)
maxBetFromBonus	No	Max stake per bet from bonus (cents)
durationDays	Yes	Days before bonus expires
forfeitOnWithdrawal	No	If true, bonus forfeits on sportsbook withdrawal
maxPerUser	No	Max activations per user (null = unlimited)

---

Bonus Types

Type	How it works
deposit_match	Matches a deposit. 100% match on 50 EUR = 50 EUR bonus.
free_bet	Free bet credit with wagering requirement.
no_deposit	Bonus without deposit. Just activate.
cashback	Percentage of losses returned as bonus.
reload	Bonus on subsequent deposits (not first).

---

Wagering Mechanics

• Target = maxBonusAmount * wageringMultiplier
• Only placed bets with odds >= minOdds contribute
• Contribution = min(stakeAmount, maxBetFromBonus) per bet
• Progress is cumulative (doesn't reset on loss)
• Only one bonus active at a time per user

---

API Reference

Operator (admin)

Method	Endpoint	Purpose
GET	/v1/admin/bonus-offers	List all offers
POST	/v1/admin/bonus-offers	Create an offer
PUT	/v1/admin/bonus-offers/:id	Update an offer
DELETE	/v1/admin/bonus-offers/:id	Delete an offer
GET	/v1/admin/bonuses	List all active bonuses
POST	/v1/admin/bonuses/:id/cancel	Cancel an active bonus
POST	/v1/admin/bonuses/grant	Grant bonus to specific user
GET	/v1/admin/bonuses/stats	Bonus statistics

Public (widget key)

Method	Endpoint	Purpose
GET	/v1/users/:userId/bonuses	Active + available + completed
POST	/v1/users/:userId/bonuses/activate	Activate an available offer

Withdrawal notification

Method	Endpoint	Purpose
POST	/v1/users/:userId/withdrawal-event	Notify FAST of sportsbook withdrawal (triggers forfeit)

---

SDK Usage

const offers = await fast.admin.bonuses.listOffers();
await fast.admin.bonuses.createOffer({
  name: 'Welcome 100%',
  bonusType: 'deposit_match',
  matchPercent: 100,
  maxBonusAmount: 5000,
  wageringMultiplier: 8,
  durationDays: 30,
});

// Activate for user
await fast.admin.bonuses.activate('player-42', offerId, 5000); // 50 EUR deposit

// Notify withdrawal (triggers forfeit if applicable)
await fast.users.notifyWithdrawal('player-42', 100);

---

Webhook Events

Event	When
bonus.activated	Bonus started for user
bonus.progress	Significant wagering milestone
bonus.completed	Wagering requirement met
bonus.forfeited	Bonus cancelled/forfeited
bonus.expired	Time expired before completion