Skip to content
Beexar Docs

POST /freespins/issue

Operator → Beexar

Gives the player account freespins_quantity free rounds in the listed games, at the bet that bet_level stands for in each game and the account currency (Bet Levels), playable until valid_until. The quantity is shared by all the listed games, not given in each.

The player just launches one of the games with a normal real-money launch: the game opens with the freespins, its bet locked. When the issue is over, the total won is reported once with Freespins/Finish.

Request

Section titled “Request”

POST {GATEWAY_URL}/api/v1/softswiss/freespins/issue

Headers

Section titled “Headers”
Header Value
Content-Type application/json
X-REQUEST-SIGN HMAC-SHA256 signature of the request body (64 hex chars)

Body

Section titled “Body”
Field Type Required Description
casino_id string Yes Operator slug
issue_id string Yes Your identifier for this issue (max 255 chars). Freespins/Finish reports back under it
games string[] Yes Game slugs (min 1). The quantity is shared by all of them
freespins_quantity integer Yes Number of free rounds, 1–10000
bet_level integer Yes A level from Bet Levels — the total bet of every free round
valid_until string Yes Until when the freespins are playable, UTC with a Z (e.g. "2026-12-01T00:00:00Z"), at most one month ahead
account object Yes The player, as in a launch
account.id string Yes Player ID on your side (max 255 chars)
account.currency string Yes The player’s currency. The bet and the result are in it

The other account fields of a launch (nickname, country, …) are accepted; the issue keeps only account.id and account.currency.

Example

Section titled “Example”
{
  "casino_id": "casinoxyz",
  "issue_id": "fs-2026-000123",
  "games": ["dice", "plinko"],
  "freespins_quantity": 10,
  "bet_level": 1,
  "valid_until": "2026-12-01T00:00:00Z",
  "account": {
    "id": "player_123",
    "currency": "EUR"
  }
}

Response (200 OK)

Section titled “Response (200 OK)”
{}

Behavioral Rules

Section titled “Behavioral Rules”
  • Record the issue on your side first. Freespins/Finish carries only issue_id and amount, so your record is what tells you whose wallet, in which currency, to credit.
  • Idempotent on issue_id. Repeating an issue_id with the same terms answers 200 like the first Issue did — even when the time window has moved on since. With other terms it is refused with api_code 610, and meta.api_message names what differs.
  • Retry with the same body. A timeout or a 500 is safe to retry, but with the same terms: a valid_until computed again on the retry is other terms.
  • The bet is fixed per game. One bet_level can stand for a different amount in each game; each game’s amount is taken from its levels when the issue is created, and later changes to the game’s bet limits do not affect it.
  • The player is account.id + account.currency. The issue may arrive before the player’s first launch.
  • Canceled first, issued never. An issue_id that was canceled before it was issued is refused with 605.

Error Responses

Section titled “Error Responses”

Same envelope as the launch endpoints: branch on meta.api_code. An issue_id that already exists is answered from the stored issue before its terms are checked again — 200 for the same terms, 610 for others — so a retry never fails on a window that has moved on.

HTTP code meta.api_code Meaning
403 invalid_argument 403 Invalid request signature
400 invalid_argument 400 Malformed body, or freespins_quantity above 10000
400 invalid_argument 404 casino_id not found — Beexar has no such casino
400 invalid_argument 410 Casino is disabled
400 invalid_argument 420 This endpoint is not available for the operator’s integration type
400 invalid_argument 406 This feature is not enabled for your casino: no Freespins finish URL configured
400 invalid_argument 154 Currency not allowed
400 invalid_argument 405 A game your casino does not have
400 invalid_argument 608 A game that does not play freespins
400 invalid_argument 601 A game has no such bet_level in the currency
400 invalid_argument 602 No game
400 invalid_argument 603 valid_until is not a valid time, is in the past, or is more than one month ahead
400 invalid_argument 605 This issue_id was canceled before it was issued
400 invalid_argument 610 This issue_id was already issued with other terms
500 internal 500 Internal error — also when the casino cannot be looked up for the moment, or a game’s engine is not answering (meta.api_message names the game). Retryable with the same body

curl Example

Section titled “curl Example”
Terminal window
BODY='{"casino_id":"casinoxyz","issue_id":"fs-2026-000123","games":["dice"],"freespins_quantity":10,"bet_level":1,"valid_until":"2026-12-01T00:00:00Z","account":{"id":"player_123","currency":"EUR"}}'
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "your_auth_token" | awk '{print $2}')


curl -X POST https://gateway.beexar.com/api/v1/softswiss/freespins/issue \
  -H "Content-Type: application/json" \
  -H "X-REQUEST-SIGN: $SIGNATURE" \
  -d "$BODY"