> ## Documentation Index
> Fetch the complete documentation index at: https://docs.game-services.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Rollback

> Reverses a previously credited amount from the player's balance.

> `POST` /credit/rollback

<Note>This operation is idempotent.</Note>

### Headers

| Name                                                                | Type     | Description                                                                                                                   |
| ------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **<span style={{color: "rgb(var(--primary)"}}>X-Auth-Token</span>** | `string` | Custom authentication header in the format X-Auth-Token: your\_token\_here. This token is required to authorize API requests. |

***

### Request Parameters

| Name                                                                        | Type      | Description                                                                                                                                 |
| --------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **<span style={{color: "rgb(var(--primary)"}}>playerId</span>**             | `string`  | Unique identifier of the player.                                                                                                            |
| **<span style={{color: "rgb(var(--primary)"}}>amount</span>**               | `decimal` | Amount to rollback.                                                                                                                         |
| **<span style={{color: "rgb(var(--primary)"}}>gameUuid</span>**             | `string`  | Unique identifier of the game.                                                                                                              |
| **<span style={{color: "rgb(var(--primary)"}}>sessionId</span>**            | `string`  | Unique identifier of the player session.                                                                                                    |
| **<span style={{color: "rgb(var(--primary)"}}>promotionExternalId</span>**  | `string`  | External identifier of the promotion session. This field must be sent for promo or free bet requests and omitted for regular game requests. |
| **<span style={{color: "rgb(var(--primary)"}}>roundId</span>**              | `string`  | Unique identifier of the game round.                                                                                                        |
| **<span style={{color: "rgb(var(--primary)"}}>transactionId</span>**        | `string`  | Unique identifier of the game round transaction.                                                                                            |
| **<span style={{color: "rgb(var(--primary)"}}>transactionTimestamp</span>** | `integer` | Timestamp of the transaction in milliseconds.                                                                                               |
| **<span style={{color: "rgb(var(--primary)"}}>currency</span>**             | `string`  | Currency code of the player.                                                                                                                |

***

### Response Parameters

| Name                                                           | Type      | Description                                           |
| -------------------------------------------------------------- | --------- | ----------------------------------------------------- |
| **<span style={{color: "rgb(var(--primary)"}}>balance</span>** | `decimal` | The updated balance of the player after the rollback. |

***

### Error

<Note>If an error occurs while processing a request, the API must return a response with `HTTP Status Code: 400 Bad Request`</Note>

| Name                                                               | Type     | Description                               |
| ------------------------------------------------------------------ | -------- | ----------------------------------------- |
| **<span style={{color: "rgb(var(--primary)"}}>error\_code</span>** | `string` | Error code describing the specific issue. |

<Expandable title="Possible Error Codes">
  | Error Code                                                                       | Description                                                         |
  | -------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
  | **<span style={{color: "rgb(var(--primary)"}}>INVALID\_PLAYER\_ID</span>**       | The provided player ID is invalid or does not exist in the system.  |
  | **<span style={{color: "rgb(var(--primary)"}}>INVALID\_SESSION</span>**          | The provided session ID is invalid or does not exist in the system. |
  | **<span style={{color: "rgb(var(--primary)"}}>INVALID\_PLAYER\_CURRENCY</span>** | The player's currency is invalid or mismatched.                     |
  | **<span style={{color: "rgb(var(--primary)"}}>INVALID\_GAME</span>**             | The specified game UUID is invalid or does not exist.               |
  | **<span style={{color: "rgb(var(--primary)"}}>INVALID\_TRANSACTION</span>**      | The transaction for rollback is invalid or cannot be processed.     |
  | **<span style={{color: "rgb(var(--primary)"}}>TECHNICAL\_ERROR</span>**          | An unexpected error occurred.                                       |
  | **<span style={{color: "rgb(var(--primary)"}}>NOT\_AUTHORIZED</span>**           | The request is not authorized due to invalid X-Auth-Token header.   |
</Expandable>

***

<Warning>
  Responsibility of the wallet platform
</Warning>

The wallet platform must verify that the incoming `playerId`, `roundId`, `transactionId` and `amount` correspond to the latest wager placed in the game round. It must also ensure that no debit has been issued for the game round. If any of these assertions fail, the rollback request must be refused.

If `promotionExternalId` is present, the wallet platform must validate that it belongs to the active promotion session for the player and use it as the promo wallet context.

A rollback happens if something goes wrong during action processing and the system needs to restore the previous state. However, there are two conditions:

* There haven’t been any winnings in this round yet.
* A jackpot hasn’t been won during the round.

If the specified transaction is not found or has already been rolled back, the wallet platform must return an `INVALID_TRANSACTION` error code. This error response will be interpreted as a successful rollback, ensuring that the rollback will not be sent repeatedly.

For all other errors, the RGS platform will attempt to send the rollback again.

<ResponseExample>
  ```http Request theme={null}
  POST /credit/rollback
  Content-Type: application/json
  {
      "playerId": "123e4567-e89b-12d3-a456-426614174000",
      "amount": 20.00,
      "gameUuid": "b23e45a7-9be8-d312-56a4-174000426614",
      "sessionId": "1c4f1d6d-5e37-4a8f-e642-def88a3b4749",
      "promotionExternalId": "promo-session-123",
      "roundId": "nAanFguGKTnLMlaPtIb2MZgnpY-IzB6x94qd5refwyIjGZWJl0mHs00tM2mPHWpvLN7IE3KH6QOR",
      "transactionId": "DER6i2rKbzn6S1qzb38fKBZZ3oehgO0Um7MyYhsFcXSW1kfxw-02_bS4WNzQb0hhBU2NqqkUch-y5KyKv2fdsf4",
      "transactionTimestamp": 1632771475000,
      "currency": "USD",
  }
  ```

  ```json Response 200 theme={null}
  {
      "balance": 100.00
  }
  ```

  ```json Error 400 theme={null}
  {
      "error_code": "INVALID_TRANSACTION"
  }
  ```
</ResponseExample>