Rollback

Rollback Transaction

Overview

The Rollback method allows game providers to reverse a previously made wager. This is commonly used in error scenarios, such as when a network issue occurs after a player places a bet but before the game round completes. By rolling back the wager, the player’s funds are returned to their account, ensuring they are not charged for a game round that did not complete properly.

Some game providers require specialized rollback implementations. For example, Sports Book providers typically require support for both Rollback on Result and Rollback on Rollback operations in addition to the standard Rollback.

Flow Diagram

Casino Responsibilities

The casino platform must perform the following operations when processing a Rollback request:

1. Transaction Validation

   • Confirm that the incoming accountid, roundid, and transactionid match the original wager
   • Verify that the wager being rolled back has not already been included in a result
   • Check that no previous rollback has been processed for this transaction

2. Idempotency Check

   • Check if a request with the same transactionid has been processed before
   • If any essential fields mismatch, return “Transaction operator mismatch”
   • If no mismatches, return the original response with status “200 Success - duplicate request”

3. Session Expiry Handling

   • A rollback must be accepted even if the game session has expired
   • Return code 1000 Not logged on is never a valid response to a rollback call

4. Balance Restoration

   • Refund the player’s balance only if a successful wager was found
   • Do not refund in case of a failed wager or any other error
   • Update both real money and bonus balances as appropriate

Request Details

Endpoint

{casino_endpoint}?request=rollback&[parameters]

Request Parameters

Example Request

GET {casino_endpoint}?request=rollback&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&rollbackamount=10.0&roundid=nc8n4nd87&transactionid=trx_id

Response Details

Response Parameters

Example Success Response

{
  "code": 200,
  "status": "Success",
  "accounttransactionid": "de73550e-0612-4a1b-8a0d-a5a3745b",
  "balance": 100.00,
  "bonus_balance": 50.00,
  "real_balance": 50.00,
  "game_mode": 1,
  "order": "cash_money",
  "apiversion": "1.2"
}

Error Handling

Common Error Codes

Implementation Notes

1. Rollback Eligibility:

   • A wager can only be rolled back if no result has been processed for it
   • Once a result transaction is received, the wager can no longer be rolled back
   • In case a result needs to be rolled back, use Rollback on Result instead

2. Idempotency Handling:

   • Store transaction IDs to identify duplicate rollback requests
   • Return the original response for duplicate transactions with the same transaction ID
   • Only the balance fields may change in duplicate responses (as player balance may have changed)

3. Balance Restoration:

   • The player’s balance should be restored to its state before the wager
   • If the original wager used both real money and bonus funds, both balances should be restored accordingly

4. Timing Considerations:

   • Rollbacks may be sent significantly after the original wager
   • The system must handle rollbacks even if the player’s session has expired
   • This is particularly important for games with network issues or delayed error detection

5. Transaction Record Keeping:

   • Maintain a record of rolled back transactions for auditing and reconciliation
   • Update the status of the original wager to indicate it has been rolled back

Security

When Signature Validation is enabled:

1. Include the X-Groove-Signature header in your request
2. Calculate signature using query parameters (excluding request)
3. See Signature Validation for detailed implementation

Signature Example

For the request:

GET {casino_endpoint}?request=rollback&gamesessionid=123_jdhdujdk&accountid=111&device=desktop&gameid=80102&apiversion=1.2&rollbackamount=10.0&roundid=nc8n4nd87&transactionid=trx_id

Query parameters for signature (alphabetically sorted):

• accountid: “111”
• apiversion: “1.2”
• device: “desktop”
• gameid: “80102”
• gamesessionid: “123_jdhdujdk”
• rollbackamount: “10.0”
• roundid: “nc8n4nd87”
• transactionid: “trx_id”

Concatenated values: 1111.2desktop80102123_jdhdujdk10.0nc8n4nd87trx_id

With security key "test_key", the signature would be:

X-Groove-Signature: 5ecbc1d5c6bd0ad172c859da01cb90746a61942bdf6f878793a80af7539719e5

Related Endpoints

• Wager - The transaction that may need to be rolled back
• Rollback on Result - Used to reverse a Result transaction
• Rollback on Rollback - Used to reverse a previous Rollback transaction