Callback Configuration

Overview

Beexar needs to know where to send wallet requests during gameplay. You configure 4 callback URLs in the Beexar backoffice for each operator — and a fifth, optional one if you issue freespins.

---

Required Callbacks

Callback	Purpose	Endpoint	See
Balance URL	Fetch player balance	POST /balance	/balance
BetWin URL	Debit/credit player account (atomic)	POST /betwin	/betwin
Rollback URL	Reverse transactions	POST /rollback	/rollback
Finish URL	Round completion signal	POST /finish	/finish

Optional Callback

Callback	Purpose	Endpoint	See
Freespins finish URL	Credit what a freespins issue won, once per issue	POST /freespins/finish	/freespins/finish

Set it only if you issue freespins. While it is empty, Freespins/Issue answers api_code 406; everything else works as before.

Example Configuration

Setting	URL
Balance URL	https://api.casino.com/beexar/balance
BetWin URL	https://api.casino.com/beexar/betwin
Rollback URL	https://api.casino.com/beexar/rollback
Finish URL	https://api.casino.com/beexar/finish
Freespins finish URL (optional)	https://api.casino.com/beexar/freespins/finish

---

URL Requirements

Requirement	Details
Protocol	HTTPS required
Method	All callbacks use POST
Content-Type	application/json
Availability	URLs must be publicly accessible from Beexar servers
Response time	Should respond within 10 seconds
Authentication	X-REQUEST-SIGN header with HMAC-SHA256 signature

Caution

All URLs must be valid and reachable. If Beexar cannot reach a callback URL, the game will not function correctly — bets will be rolled back and the player experience will degrade.

---

URL Patterns

You can use different URL patterns depending on your architecture:

Separate Endpoints

balance_url:  https://api.casino.com/wallet/balance
betwin_url:   https://api.casino.com/wallet/betwin
rollback_url: https://api.casino.com/wallet/rollback
finish_url:   https://api.casino.com/wallet/finish

Single Base Path

balance_url:  https://api.casino.com/beexar/v1/balance
betwin_url:   https://api.casino.com/beexar/v1/betwin
rollback_url: https://api.casino.com/beexar/v1/rollback
finish_url:   https://api.casino.com/beexar/v1/finish
freespins_finish_url: https://api.casino.com/beexar/v1/freespins/finish

Tip

The official SDKs route on the path suffix, longest route first, so …/freespins/finish and …/finish can share one prefix. Keep the /freespins/finish ending if you use an SDK.

---

Configuring in the Backoffice

Callback URLs are configured per-operator in the Beexar backoffice:

1. Log in to the Beexar backoffice
2. Navigate to Operators and select your operator
3. Go to the Callback URLs tab
4. Enter the 4 callback URLs, and the Freespins finish URL if you issue freespins
5. Save the configuration

See the Backoffice: API Keys & Callbacks guide for step-by-step instructions with screenshots.

Changes take effect immediately for new game sessions. Existing sessions continue using the URLs that were configured at session creation time.

---

Beexar Retry Behavior

When Beexar calls your callback URLs and encounters an error:

Scenario	Beexar Action
Connection refused	Retry up to 3 times, then return error to player
Timeout	Retry up to 3 times, then return error to player
HTTP 500	Retry up to 3 times, then return error to player
HTTP 400 (api_code 100)	No retry, show “insufficient funds” to player
HTTP 400 (other)	No retry, log error
Invalid JSON response	No retry, return error to player

/freespins/finish is not tied to a player action and has its own schedule: retried after 1, 3 and 5 minutes, then every 5 minutes (15 seconds per attempt), until you answer 200 — refusals included.

---

Health Monitoring

We recommend implementing monitoring for your callback endpoints:

• Uptime: 99.9% availability target
• Latency: P99 < 1 second, P50 < 200ms
• Error rate: < 0.1% non-business errors (exclude code 100)
• Alerting: Set up alerts for response time spikes and error rate increases