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

# Credit Debit

> Credits the creditAmount from the player's balance and debits the debitAmount to the player's balance.

> `POST` /credit-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)"}}>creditAmount</span>**         | `decimal` | Amount to credit.                                                                                                                           |
| **<span style={{color: "rgb(var(--primary)"}}>debitAmount</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., 'CREDIT\_DEBIT\_SPIN'.                                                                                           |
| **<span style={{color: "rgb(var(--primary)"}}>transactionTimestamp</span>** | `integer` | Timestamp of the transaction in milliseconds.                                                                                               |
| **<span style={{color: "rgb(var(--primary)"}}>roundStarted</span>**         | `boolean` | Flag indicating start of the round.                                                                                                         |
| **<span style={{color: "rgb(var(--primary)"}}>roundFinished</span>**        | `boolean` | Flag indicating end 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>

* `CREDIT_DEBIT_SPIN`: A regular spin-based transaction.
* `CREDIT_DEBIT_PURCHASE`: A transaction where the player directly purchases a bonus feature within the game.
* `FREEBET_CREDIT_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\_STARTED</span>**   | The bet has already been initiated and cannot be repeated.          |
  | **<span style={{color: "rgb(var(--primary)"}}>INSUFFICIENT\_FUNDS</span>**       | The player does not have enough funds to complete the action.       |
  | **<span style={{color: "rgb(var(--primary)"}}>BET\_NOT\_ALLOWED</span>**         | Bet is not allowed for the specified conditions.                    |
  | **<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 sessionId is valid and correctly associated with the provided playerId.

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.

The wallet platform should ensure that creditAmount is not less than the player's balance before transaction. INSUFFICIENT\_FUNDS error should be returned otherwise.

In addition, it should persist `roundId`, `playerId`, `transactionId` and `amount` to ensure that future debit or rollback operations can be reliably processed, maintaining the integrity of the player's balance throughout the game session.

<ResponseExample>
  ```http Request theme={null}
  POST /credit-debit
  Content-Type: application/json
  {
      "playerId": "123e4567-e89b-12d3-a456-426614174000",
      "creditAmount": 20.00,
      "debitAmount": 0.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_CREDIT_DEBIT_SPIN",
      "transactionTimestamp": 1632771475000,
      "roundStarted": true,
      "roundFinished": false,
      "currency": "USD",
  }

  ```

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

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