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) of the session that opened the round — the one the reversed /betwin carried

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": "dice",
  "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": "dice",
    "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
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" }