POST /rollback

Beexar → Operator

Beexar sends this request to reverse previously processed transactions (bets or wins). The operator must undo the financial effect of each original transaction.

---

Request

POST {rollback_url}

Headers

Header	Value
Content-Type	application/json
X-REQUEST-SIGN	HMAC-SHA256 signature of request body

Body

Field	Type	Required	Description
account_id	string	Yes	Player account identifier
currency	string	Yes	Currency code — standard ("USD", "EUR") or custom ("CUSTOM_GOLD")
game_id	string	Yes	Game identifier (slug)
round_id_provider	string	Yes	Game round identifier (Beexar’s round_id)
finished	boolean	Yes	Whether the game round is finished after this rollback
transactions	array	Yes	List of rollback transactions (min 1)
session_id	string	No	Session identifier (UUID)

Transaction Object

Each item in the transactions array:

Field	Type	Required	Description
id_provider	string	Yes	Unique rollback transaction identifier (generated by Beexar)
type	string	Yes	Always "rollback"
original_id_provider	string	Yes	id_provider of the original transaction to reverse

Note

The rollback request does not include an amount field. The operator determines the amount to reverse based on the original_id_provider.

Example

{
  "account_id": "player_123",
  "currency": "USD",
  "game_id": "slots",
  "round_id_provider": "550e8400-e29b-41d4-a716-446655440000",
  "finished": true,
  "transactions": [
    {
      "id_provider": "tx_rb_001",
      "type": "rollback",
      "original_id_provider": "tx_bet_001"
    }
  ],
  "session_id": "7b115688-3849-490a-95bd-7c281d81c64c"
}

---

Response

Success (200 OK)

Field	Type	Required	Description
balance	string	Yes	Player balance after rollback
round_id	string	Yes	Round identifier on operator side
transactions	array	Yes	Results for each rollback transaction

Each transaction result:

Field	Type	Required	Description
id_provider	string	Yes	Rollback transaction identifier from request (echo back)
id	string	Yes	Transaction identifier assigned by operator (may be empty if original was not found)

{
  "balance": "500.00",
  "round_id": "697962ac-fd0d-4dc2-b52c-e850e40825dc",
  "transactions": [
    { "id_provider": "tx_rb_001", "id": "op_tx_201" }
  ]
}

Error Responses

HTTP Status	Twirp Code	api_code	Description
400	invalid_argument	403	Invalid or missing signature
500	internal	500	Internal server error

---

curl Example

curl -X POST https://casino.example.com/wallet/rollback \
  -H "Content-Type: application/json" \
  -H "X-REQUEST-SIGN: abc123def456..." \
  -d '{
    "account_id": "player_123",
    "currency": "USD",
    "game_id": "slots",
    "round_id_provider": "550e8400-e29b-41d4-a716-446655440000",
    "finished": true,
    "transactions": [
      {
        "id_provider": "tx_rb_001",
        "type": "rollback",
        "original_id_provider": "tx_bet_001"
      }
    ]
  }'

---

Behavioral Rules

These rules are critical for correct rollback implementation:

1. If the original transaction exists — reverse it and return the updated balance

   • Rollback of a bet → credit the bet amount back to the player
   • Rollback of a win → debit the win amount from the player

2. If the original transaction does NOT exist — create a tombstone and return a valid response (NOT an error)

   • The tombstone prevents the original transaction from being processed if it arrives later
   • This handles the case where rollback arrives before the original transaction due to network timing

3. Tombstone prevents late processing — if a BetWin arrives and a tombstone exists for that id_provider, the transaction must be rejected (api_code 155)

4. Process rollback even if player has insufficient funds — if rolling back a win would make the balance negative, still process it

5. Duplicate rollback — if the same id_provider is received again, return the original response, do NOT reverse the transaction again

6. Idempotency applies to id_provider (the rollback’s own ID), not original_id_provider

Danger

Never return an error when the original transaction doesn’t exist. Always create a tombstone and respond with 200 OK. This is essential for data consistency.

---

When Does Beexar Send Rollback?

Trigger	Description
Game error	An error occurred in the game engine after the bet was confirmed but before the result was determined
Bonus/Free-Spins timeout	In multi-step games (slots), if the player does not complete a bonus or free-spins session within the timeout period
Crash game win failure	If the win wallet call fails during cashout, the win is rolled back asynchronously
Stale bets	If a bet is stuck in a transitional state for too long, the system rolls it back automatically

Note

Beexar does not send a rollback after a timed-out or failed bet request. If the operator does not respond and all retries are exhausted, the round is considered “not started”. See Error Handling for details.

---

Sequence Diagram

sequenceDiagram
    participant Beexar
    participant Wallet as Operator Wallet

    Note over Beexar,Wallet: Scenario 1: Normal rollback
    Beexar->>Wallet: POST /betwin (bet tx_bet_1)
    Wallet-->>Beexar: 200 OK
    Beexar->>Wallet: POST /rollback (original: tx_bet_1)
    Wallet->>Wallet: Reverse bet, credit player
    Wallet-->>Beexar: 200 { balance }

    Note over Beexar,Wallet: Scenario 2: Tombstone (rollback before bet)
    Beexar->>Wallet: POST /rollback (original: tx_bet_2)
    Wallet->>Wallet: tx_bet_2 not found, create tombstone
    Wallet-->>Beexar: 200 { balance }
    Note right of Wallet: Later, if tx_bet_2 arrives...
    Beexar->>Wallet: POST /betwin (bet tx_bet_2)
    Wallet->>Wallet: Tombstone exists, reject
    Wallet-->>Beexar: 400 { api_code: "155" }