> ## 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.

# Debit

> Debits the specified amount to the player's balance.

> `POST` /debit

<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 debit.                                                                                                                            |
| **<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)"}}>transactionType</span>**      | `string`  | Type of transaction, e.g., 'DEBIT\_SPIN'.                                                                                                   |
| **<span style={{color: "rgb(var(--primary)"}}>transactionTimestamp</span>** | `integer` | Timestamp of the transaction in milliseconds.                                                                                               |
| **<span style={{color: "rgb(var(--primary)"}}>roundFinished</span>**        | `boolean` | Flag indicating finish of the round.                                                                                                        |
| **<span style={{color: "rgb(var(--primary)"}}>currency</span>**             | `string`  | Currency code of the player.                                                                                                                |

<Tip>Transaction Types: Enum representing the type of transaction.</Tip>

* `DEBIT_SPIN`: A regular spin-based transaction.
* `DEBIT_JACKPOT`: A transaction where the player receives a jackpot payout.
* `FREEBET_DEBIT_SPIN`: A free bet spin transaction.

***

### Response Parameters

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

***

### 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)"}}>ROUND\_ALREADY\_FINISHED</span>**  | The game round has already ended.                                   |
  | **<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 and roundId correspond to a previously placed wager. If this validation fails, the debit 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.

If the `roundFinished` has been marked as true, the platform must close the round, ensuring that no new Credit, Debit or Rollback operations can be performed on it.

<ResponseExample>
  ```http Request theme={null}
  POST /debit
  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",
      "transactionType": "FREEBET_DEBIT_SPIN",
      "transactionTimestamp": 1632771475000,
      "roundFinished": false,
      "currency": "USD"
  }
  ```

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

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