> ## Documentation Index
> Fetch the complete documentation index at: https://walletapi.oppigames.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payout

> This API is triggered when the player wins. It increases the player's balance by the payout amount and returns the updated balance.

```http theme={null}
  POST  /transaction/payout
```

## Functionality

The endpoint called when the player wins (credit)

* The Operator is expected to increase player's balance by payout and return a new balance.
* Each win has transactionId which is unique for each transaction. Before any altering of player's balance, Operator has to check that win wasn't processed before.
* If the payout fails, the system will automatically retry up to three times. If all retries fail, the bet will also be marked as failed to ensure transaction consistency, and a revert operation will be triggered.

Finally, it returns the updated balance, reflecting the result of the win.

## Headers

<ParamField header="x-api-key" type="string" required>
  A unique identifier associated with operator calling API.
</ParamField>

<ParamField header="x-signature" type="string" required>
  A SHA256 HMAC signature generated using the request body and timestamp.
  Format: HMAC\_SHA256(JSON.stringify(data) + '|' + timestamp), signed using the
  provided secret key.
</ParamField>

<ParamField header="x-timestamp" type="string" required>
  An Unix timestamp (milliseconds) when the request was sent. Ensure the same
  value is used in signature generation.
</ParamField>

<ParamField header="content-type" type="string" required>
  Must be set to `application/json`
</ParamField>

## Request Body

<ParamField body="transactionId" type="string" required>
  The unique transaction identifier. An action with same transactionId shouldn't be processed more than once.
</ParamField>

<ParamField body="refTransactionId" type="string" required>
  Unique identifier of the transaction that this transaction is referencing, which is the transactionId of the bet.
</ParamField>

<ParamField body="sessionId" type="string" required>
  A unique identifier for the session.
</ParamField>

<ParamField body="playerId" type="string" required>
  The unique identifier for the player.
</ParamField>

<ParamField body="gameId" type="string" required>
  The unique identifier for the game.
</ParamField>

<ParamField body="currency" type="string" required>
  Player's current session currency code.
</ParamField>

<ParamField body="amount" type="number" required>
  The amount won by the player.

  <Note>
    To maintain precision and avoid floating-point errors, the amount field is processed as an integer value by multiplying the actual amount by `100000`.

    For example, a amount of `12.34567` will be represented as `1234567` in the API.
  </Note>
</ParamField>

<ParamField body="isWin" type="boolean" required>
  Indicates whether the player won the bet.
</ParamField>

<ParamField body="isFreeBet" type="boolean" required>
  Indicates whether the bet transaction was placed using a free bet bonus.

  true → The bet is made using a free bet bonus.

  false → The bet is made using regular funds.
</ParamField>

<ParamField body="bonusData" type="object" required>
  Contains the currently active bonus information

  <Expandable title="properties">
    <ParamField body="bonusId" type="string" required>
      The unique identifier for the bonus.
    </ParamField>

    <ParamField body="bonusType" type="string" required>
      Type or category of the bonus.
    </ParamField>

    <ParamField body="totalSpin" type="number" required>
      Total number of spins granted in the bonus.
    </ParamField>

    <ParamField body="remainingSpin" type="number" required>
      Number of bonus spins remaining.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="status" type="string" required>
  Code indicates status of the request weather it is succeed or failed. We have listed error codes <a href="/introduction#error-codes">here</a>
</ResponseField>

<ResponseField name="transactionId" type="string" required>
  An ID of an action that is generated for each of our calls to the Operator, used to sync OppiGame and Operator sides for debugging purposes. The Operator has to respond with the same transactionId as the one received in request.
</ResponseField>

<ResponseField name="balance" type="number" required>
  The updated balance of the player.

  <Note>
    To maintain precision and avoid floating-point errors, the balance field is processed as an integer value by multiplying the actual amount by `100000`.

    For example, a balance of `12.34567` will be represented as `1234567` in the API.
  </Note>
</ResponseField>

<RequestExample>
  ```bash Shell theme={null}
  curl --request POST \
    --url 'https://partner-platform-url/transaction/payout' \
     --header 'content-type: application/json' \
    --header 'x-api-key: <x-api-key>' \
    --header 'x-signature: <x-signature>' \
    --header 'x-timestamp: <x-timestamp>' \
    --data '{
      "transactionId": "be41ea4b-8131-4e35-87cb-5a3b99a88469",
      "refTransactionId": "1db4fac5-34b2-4b81-a101-c105979633e0",
      "sessionId": "f1dfc865-584c-4cba-a175-06172b2a41141731504451691",
      "playerId": "18865671",
      "gameId": "G1720767064793",
      "currency": "EUR",
      "amount": 10000000,
      "isWin": true,
      "isFreeBet" : true,
      "bonusData": {
         bonusId: "f1dfc865-584c-4cba-a175-06172b2a41141731504451691",
         bonusType: "Free Bets",
         totalSpin: 15,
         remainingSpin: 10,
      }
  }
  ```

  ```javascript NodeJS theme={null}
  const axios = require('axios');

  const url = 'https://partner-platform-url/transaction/payout';
  const headers = {
      'content-type': 'application/json',
      'x-api-key': '<x-api-key>',
      'x-signature': '<x-signature>',
      'x-timestamp': '<x-timestamp>'
  };
  const data = {
      transactionId: "be41ea4b-8131-4e35-87cb-5a3b99a88469",
      refTransactionId: "1db4fac5-34b2-4b81-a101-c105979633e0",
      sessionId: "f1dfc865-584c-4cba-a175-06172b2a41141731504451691",
      playerId: "18865671",
      gameId: "G1720767064793",
      currency: "EUR",
      amount: 10000000,
      isWin: true,
      isFreeBet : true,
      bonusData: {
         bonusId: "f1dfc865-584c-4cba-a175-06172b2a41141731504451691",
         bonusType: "Free Bets",
         totalSpin: 15,
         remainingSpin: 10,
      }
  };

  axios.post(url, data, { headers })
      .then(response => {
          console.log(response.data);
      })
      .catch(error => {
          console.error(error);
      });
  ```

  ```python Python theme={null}
  import requests

  url = "https://partner-platform-url/transaction/payout"
  headers = {
      "content-type": "application/json",
      "x-api-key": "<x-api-key>",
      "x-signature": "<x-signature>",
      "x-timestamp": "<x-timestamp>"
  }
  data = {
      "transactionId": "be41ea4b-8131-4e35-87cb-5a3b99a88469",
      "refTransactionId": "1db4fac5-34b2-4b81-a101-c105979633e0",
      "sessionId": "f1dfc865-584c-4cba-a175-06172b2a41141731504451691"
      "playerId": "18865671",
      "gameId": "G1720767064793",
      "currency": "EUR",
      "amount": 10000000,
      "isWin": true,
      "isFreeBet" : true,
      "bonusData": {
         "bonusId": "f1dfc865-584c-4cba-a175-06172b2a41141731504451691",
         "bonusType": "Free Bets",
         "totalSpin": 15,
         "remainingSpin": 10,
      }
  }

  response = requests.post(url, headers=headers, json=data)
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://partner-platform-url/transaction/payout",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "content-type: application/json",
      "x-api-key: <x-api-key>",
      "x-signature: <x-signature>",
      "x-timestamp: <x-timestamp>"
    ],
    CURLOPT_POSTFIELDS => json_encode([
      "transactionId" => "be41ea4b-8131-4e35-87cb-5a3b99a88469",
      "refTransactionId" => "1db4fac5-34b2-4b81-a101-c105979633e0",
      "sessionId" => "f1dfc865-584c-4cba-a175-06172b2a41141731504451691"
      "playerId" => "18865671",
      "gameId" => "G1720767064793",
      "currency" => "EUR",
      "amount" => 10000000,
      "isWin" => true,
      "isFreeBet" => true,
      "bonusData"=> {
         "bonusId": "f1dfc865-584c-4cba-a175-06172b2a41141731504451691",
         "bonusType": "Free Bets",
         "totalSpin": 15,
         "remainingSpin": 10,
      }
    ]),
  ]);

  $response = curl_exec($curl);
  curl_close($curl);

  echo $response;
  ?>
  ```
</RequestExample>

<ResponseExample>
  ```json SUCCESS theme={null}
  {
    "status": "RS_OK",
    "transactionId": "be41ea4b-8131-4e35-87cb-5a3b99a88469",
    "balance": 510000000
  }
  ```

  ```json SUCCESS FAILURE 1 theme={null}
  {
    "status": "RS_ERROR_DUPLICATE_TRANSACTION",
    "transactionId": "be41ea4b-8131-4e35-87cb-5a3b99a88469",
    "balance": 500000000
  }
  ```

  ```json SUCCESS FAILURE 2 theme={null}
  {
    "status": "RS_ERROR_NOT_ENOUGH_MONEY",
    "transactionId": "be41ea4b-8131-4e35-87cb-5a3b99a88469",
    "balance": 100000
  }
  ```

  ```json FAILURE theme={null}
  {
    "status": "RS_ERROR",
    "message": "Oops! Something went wrong. Please refresh the page or try again in a moment"
  }
  ```
</ResponseExample>