Rollback

Your integration layer uses this endpoint to reverse a specific debit transaction during a game session. This process is crucial when a game action needs to be undone, ensuring that the player’s balance is correctly adjusted back to its state before the transaction.

When a rollback is required, your integration layer sends parameters like player_id, site_id, token, and other transaction-related fields. It reverses the specified transaction, updating the player’s balance accordingly. The endpoint ensures the validity of the provided token and other data before processing the rollback, maintaining the integrity of the player’s session and wallet.

Key Points link

• Purpose: To reverse a specific transaction, such as when a bet needs to be canceled or an error is corrected.
• Process: Validates the provided token and player information, then processes the rollback transaction with detailed tracking.
• Security: Ensures that only authorized and valid requests are processed, safeguarding the player’s funds.

This endpoint is essential for managing corrections and reversals during game sessions, providing secure and accurate balance adjustments linked to specific transactions.

Note

This endpoint requires HTTP/2 for optimal performance, it is recommended to send your requests using HTTP/2. The HTTP/2 protocol enables multiplexing, allowing multiple requests and responses to be sent simultaneously over a single TCP connection. This reduces latency and improves efficiency, especially in high-throughput scenarios like gaming platforms. Ensure your integration client supports HTTP/2 to achieve faster response times and better scalability.

POST /api/wallet/rollback link

Request Headers:

• Content-Type - application/json
• Accept - application/json
• Authorization - Calculation
• X-Request-Signature - Calculation

JSON Parameters:

• token (string) - The token provided via query parameters in the launch URL.
• player_id (unsigned big integer) - The Integrator player ID provided via query parameters in the launch URL.
• site_id (unsigned big integer) - The Integrator site ID provided via query parameters in the launch URL.
• provider_id (unsigned big integer) - The provider ID assigned by us for the provider you are integrating.
• game_id (string) - The game ID you provided to us.
• currency (string) - The currency provided via query parameters in the launch URL.
• amount (unsigned float) - The amount associated with the rollback transaction. This value specifies the amount being reversed back into the player’s balance, matching the original debit action.
• round_id (string) - A unique identifier for the game round associated with the debit transaction. This ID links the transaction to the specific gameplay instance. We do not accept multiple debits within a single round. If your game type sends more than one debit in a round, please use the debit transaction ID as the round ID instead. Maximum length: 36 characters.
• transaction_id (string) - A unique identifier for the rollback transaction, ensuring that each action is uniquely tracked and logged. Maximum length: 36 characters.
• reference_transaction_id (string) - A unique identifier for the debit transaction being reversed, ensuring that the rollback is accurately associated with the corresponding debit action. Maximum length: 36 characters.
• round_closed (boolean) - A flag indicating whether the current game round is closed. This helps in determining the status and finality of the rollback action.

Response Headers:

• Content-Type - application/json

Response JSON Object:

• status (boolean) - Indicates whether the request was successful or not. A value of true means the operation was successful, while false indicates an error or failure.
• code (unsigned big integer) - A unique code representing the result of the request.
• message (string) - A human-readable message providing additional information about the status of the request. This message can include details about errors or successes.
• request_id (uuid) - A unique identifier for the specific request, used for tracking and logging purposes. It helps in tracing the request throughout the system for debugging or support.
• token (string) - The same token that was provided in the request, returned for reference and validation purposes. This ensures the response corresponds to the correct session and player.
• player_id (unsigned big integer) - The player ID associated with the rollback request, confirming the identity of the player whose balance is being adjusted.
• game_id (unsigned big integer) - The game ID represents the internal game ID in our system.
• site_id (unsigned big integer) - The site ID associated with the request, linking the transaction to a specific platform or environment. This ensures that all operations are correctly attributed to the appropriate site where the player is accessing the service.
• provider_id (unsigned big integer) - The provider ID as specified in the request, identifying the provider associated with the game session.
• balance (unsigned float) - The player’s current wallet balance after the rollback operation, reflecting the latest available funds in the account.

Status Codes:

• The HTTP status code returned by the API corresponds to the code value included in the response.

Request:

  POST /api/wallet/rollback HTTP/2
Host: environment
Authorization: Basic <encoded_credentials>
X-Request-Signature: <calculated-signature>
Content-Type: application/json
Accept: application/json

{
  "token": "3dc8fe01-2018-486e-9632-35aef21028a5",
  "player_id": 1,
  "site_id": 1,
  "provider_id": 1,
  "game_id": "example",
  "currency": "EUR",
  "amount": 50.50,
  "round_id": "ebe18296b1d7d42e1d2181d43a1c9cb5",
  "transaction_id": "d47ac10b-58cc-4372-a567-0e02b2c3d479",
  "reference_transaction_id": "73aa34d0851df1ebde09b82506da4329",
  "round_closed": true
}
  

Success Response:

  HTTP/2 200 OK
Content-Type: application/json

{
  "status": true,
  "code": 1,
  "message": "",
  "request_id": "89aac521-7a56-4ad1-8310-1ed2bbf9e55d",
  "token": "3dc8fe01-2018-486e-9632-35aef21028a5",
  "player_id": 1,
  "game_id": "example",
  "site_id": 1,
  "provider_id": 1,
  "balance": 19575.50
}
  

Failed Response:

  HTTP/2 500 Internal Server Error
Content-Type: application/json

{
  "status": false,
  "code": 2,
  "message": "An unknown error has occurred.",
  "request_id": "4d5a42b3-62ec-40cb-b5e9-b338f194ce60"
}
  

Note

If the parameter round_closed has been set to true in the request, no further actions can be performed on the same round. This restriction is in place to ensure the integrity and consistency of game sessions, preventing any changes or transactions after a round has been closed. Once a round is marked as closed, it is considered finalized, and all related transactions are locked. Any attempt to perform actions such as debit, rollback, or credit on a closed round will result in an error response, maintaining the integrity of the gameplay and preventing unauthorized modifications.

Retry Scenarios link

If you receive any of the following response codes in the response JSON object, your integration layer must retry the request to ensure successful transaction processing:

These errors indicate an issue that may have affected the transaction, requiring a retry to maintain accurate financial records and prevent incorrect balance adjustments.

Warning

If you receive a TransactionNotFoundError or BetTransactionNotFoundInRoundError, you should retry the request up to a maximum of 3 times to allow for potential transient issues.

Retry Delay link

To manage retries, apply a logarithmic delay between each attempt using the following formula:

  delay(n) = round( 1000 * log(n + 1) )
  

Where:

• n is the retry attempt number (starting from 1).
• delay(n) is the delay time in seconds, rounded to the nearest whole number.

For example:

• 1st retry (n=1): delay = 1000 x log(2) = 301 seconds
• 2nd retry (n=2): delay = 1000 x log(3) = 477 seconds
• 3rd retry (n=3): delay = 1000 x log(4) = 602 seconds
• 4th retry (n=4): delay = 1000 x log(5) = 699 seconds
• …
• 10th retry (n=4): delay = 1000 x log(10) = 1000 seconds
• And so on, up to a maximum of 10 retries.

This method ensures that retries happen with progressively increasing intervals, helping to avoid overwhelming the system while giving each attempt a better chance of success.

Warning

During retry attempts, it is important to ensure a seamless gaming experience for the player. If the player refreshes the game or obtains a new session while retries are in progress, they should be able to continue playing without interruption.

The retry process is strictly related to transaction confirmation and should never block or prevent the player from interacting with the game. Any transient or failed request retries must be handled transparently in the background by your integration layer, ensuring that the game session remains responsive and uninterrupted.