# Loyalty Integration

### Component diagram <a href="#components-diagram" id="components-diagram"></a>

<figure><img src="https://430841950-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjvZELq9hA9JLIUfXr0fB%2Fuploads%2FO2UtHxmHiIW4vOIsEYkL%2F3.jpg?alt=media&#x26;token=9a28cc41-21fe-4fc2-abee-fc7efb8f7037" alt=""><figcaption></figcaption></figure>

**Step 1:** To start Trueplay integration, the operator should provide access to game data through the Send Game Transaction endpoint.

**Step 2:** The Trueplay specialist receives data, sets up a user account in the database, and creates a Trueplay ID.

**Note:** The first time a user visits the Trueplay loyalty program page, they are immediately added to the Trueplay database.

**Step 3:** The operator integrates the Get Loyalty Page endpoint and receives a link to the loyalty program.

**Step 4:** To allow users to make deposits and withdrawals, the operator should set up the following endpoints:

* ***Get User Balance:*** to notify Trueplay about the user’s current balance.
* ***Token Exchange:*** for Trueplay to refresh the user’s balance when they make a withdrawal.

**Note:** Trueplay sends a payment notification when a user purchases tokens in the player’s account currency.

**Step 5:** The integration requires several endpoints to enable users to receive tokens for Marketing Campaigns:

* **Tokens for Registration:** This means that the user will receive tokens when placing the first bet or visiting the loyalty page.
  * If it is necessary to credit tokens before the user performs these actions, there is an optional Create User endpoint, which adds a user to the Trueplay database.
  * The user gets registration tokens right after Trueplay receives a request.
* **KYC Tokens:** The operator must notify Trueplay that the user has passed KYC.
  * Afterward, the operator should set up the Update User Account endpoint to change the status of passing the KYC verification from false to true.
* **Deposit Tokens:** In the admin panel, navigating to the Marketing Campaigns section, the operator should create a promo campaign and add users who made a deposit using the Deposit API method.

**IMPORTANT:**&#x20;

1. Operators need to whitelist the Trueplay IPs to receive callbacks about the status of transactions. Otherwise, Trueplay will return errors for deposit/withdrawal tokens requests.

<details>

<summary><strong>IPs for whitelisting</strong></summary>

18.193.249.95

18.184.86.250

18.196.113.251

</details>

2. All operator IP addresses must be whitelisted within the Trueplay system before traffic can be sent. You can add and manage your IPs through the Trueplay Admin Panel.

#### Important aspects **for cashback calculation**

If your platform offers sports betting, the operator should make the following updates:

* For WIN transactions on the Sportsbook game type, the operator must send transactions with losses as WIN = 0.
* In the reference ID parameter, for other WIN type transactions connected to the Sportsbook game type, the operator should send the BET identifier relevant to the reward.

**IMPORTANT!** WIN = 0 transactions require a unique transaction identifier.

## Trueplay endpoints <a href="#trueplay-endpoints" id="trueplay-endpoints"></a>

## Get Loyalty page&#x20;

### Authorized user

<mark style="color:blue;">`GET`</mark> `https://integration.trueplay.io/api/v2/user/{operatorUserId}/widget?language=EN`

**Method Description:** This method allows authorized users to retrieve a link to the loyalty page, suitable for embedding within an iframe on the casino platform.

In the request, you need to indicate:

* operatorUserId
* X-API key
* language

In response, you will receive a URL of the page that has to be displayed through an iframe on the casino side.

#### Path Parameters

| Name                                             | Type   | Description                 |
| ------------------------------------------------ | ------ | --------------------------- |
| operatorUserId<mark style="color:red;">\*</mark> | String | ID of user on Operator side |

#### Query Parameters

| Name                                       | Type   | Description                                                                                                                                                                 |
| ------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| language<mark style="color:red;">\*</mark> | String | <p>Localization of user loyalty page<br>Default language of loyalty page: EN</p><p>Available languages:  BN, CS, DE, EN, ES, FR, HU, ID, JA, LT, LV, PL, PT, RU, SK, TR</p> |
| view                                       | String | <p>Allows to open the required view of the loyalty page.<br>Available view: account, analytics, deposit, withdraw, token-sale, stream</p>                                   |

#### Headers

| Name                                        | Type   | Description                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------ |
| X-API-KEY<mark style="color:red;">\*</mark> | String | Operator key issued by TruePlay to access TruePlay API |

{% tabs %}
{% tab title="200: OK Request is succesful" %}
{% code overflow="wrap" %}

```json
{
"url": "https://widget.trueplay.io?token=eyJhbGciOiJIUzUxMiJ9.eyJpZF9vcGVyYXRvciI6MSwiaWRfdXNlciI6NzUxMSwicm9sZSI6IlJPTEVfVVNFUiIsImV4cCI6MTYzNDY0NjA5Mn0.umIbsJCJAQmATaVj50nS1uFAhWpLLf3Ztq953aomIS7Vl5Es-BlHuKdof_CYGBcAsimR3q1K1_3LmDZXB8iC8w” 
}
```

{% endcode %}
{% endtab %}

{% tab title="400: Bad Request Invalid request parameters provided" %}

{% endtab %}

{% tab title="401: Unauthorized Requester is unauthorized to perform an action" %}

```
{
  "message": "Authentication is required to access this resource"
}
```

{% endtab %}

{% tab title="403: Forbidden Requester is forbidden to perform an action" %}

{% endtab %}

{% tab title="404: Not Found Resource not found" %}

{% endtab %}
{% endtabs %}

### Anonymous user

<mark style="color:blue;">`GET`</mark>&#x20;

`https://integration.trueplay.io/api/v2/user/widget`

**Method Description:** This method allows anonymous users to retrieve a link to the loyalty page, suitable for embedding within an iframe on the casino platform.

#### Headers

| Name                                        | Type   | Description                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------ |
| X-API-KEY<mark style="color:red;">\*</mark> | String | Operator key issued by TruePlay to access TruePlay API |

**Example response**

{% tabs %}
{% tab title="200: OK Request is succesful" %}
{% code overflow="wrap" %}

```javascript
{
"url": "https://widget.trueplay.io?token=eyJhbGciOiJIUzUxMiJ9.eyJpZF9vcGVyYXRvciI6MSwiaWRfdXNlciI6NzUxMSwicm9sZSI6IlJPTEVfVVNFUiIsImV4cCI6MTYzNDY0NjA5Mn0.umIbsJCJAQmATaVj50nS1uFAhWpLLf3Ztq953aomIS7Vl5Es-BlHuKdof_CYGBcAsimR3q1K1_3LmDZXB8iC8w” 
}
```

{% endcode %}
{% endtab %}

{% tab title="400: Bad Request Invalid request parameters provided" %}

{% endtab %}

{% tab title="401: Unauthorized Requester is unauthorized to perform an action" %}

```
{
  "message": "Authentication is required to access this resource"
}
```

{% endtab %}

{% tab title="403: Forbidden Requester is forbidden to perform an action" %}

{% endtab %}

{% tab title="404: Not Found Resource not found" %}

{% endtab %}
{% endtabs %}

## Get transaction data

### **Get user loyalty balance**

<mark style="color:blue;">`GET`</mark> `https://integration.trueplay.io/api/v1/user/{operatorUserId}/balance`

**Method Description:** This method retrieves the user's balance on the loyalty page, allowing the operator to display this balance within the casino platform.

In the request, you need to indicate:

* operatorUserId
* X-API key

In response you will receive the user's token balance on the loyalty page.

#### Path Parameters

| Name                                             | Type   | Description                 |
| ------------------------------------------------ | ------ | --------------------------- |
| operatorUserId<mark style="color:red;">\*</mark> | String | ID of user on Operator side |

#### Headers

| Name                                        | Type   | Description                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------ |
| X-API-KEY<mark style="color:red;">\*</mark> | String | Operator key issued by TruePlay to access TruePlay API |

**Example:**

{% tabs %}
{% tab title="200: OK Request is sucessful" %}

```json
{
  "balance": 0.0001
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid request parameters provided" %}

{% endtab %}

{% tab title="Untitled" %}

{% endtab %}

{% tab title="401: Unauthorized Requester is unauthorized to perform an action" %}

{% endtab %}

{% tab title="403: Forbidden Requester is forbidden to perform an action" %}

{% endtab %}

{% tab title="404 Resource not found" %}

{% endtab %}
{% endtabs %}

### Send game transaction

<mark style="color:green;">`POST`</mark>&#x20;

`https://{operator-name}.proxy.trueplay.io/api/v1/accept`

**Method Description:** This method allows operators to send game transaction data to Trueplay. Each transaction should include essential details to support the core functionality of the Trueplay Loyalty system.

The data on game transactions is required for:

* the accrual of Play to Earn rewards to users for each bet
* the calculation GGR project for the accrual of rewards to participants of the Hold to Earn program
* Flexible mission evaluation based on transaction metadata

**IMPORTANT!**&#x20;

> Correct use of transaction types is required for accurate reward calculation:

* BET, WIN - core game actions
* ROLLBACK - cancels a previous BET or WIN

Particularities of data transmission:

* Cashout transactions for sports bets need to be passed as WIN.
* Sportbook initial transaction must be sent with parameter Type = Sportbook
* Sportbook outcomes must be sent with parameter Type = Win and reference TransactionId (initial transaction identifier). Transaction Amount depends on bet outcome type:
  * winning bet — Amount is equal to amount won
  * losing bet — Amount is 0
  * cashout done — Amount is equal to cashout amount

#### Headers

| Name                                        | Type   | Description                                       |
| ------------------------------------------- | ------ | ------------------------------------------------- |
| X-API-KEY<mark style="color:red;">\*</mark> | String | Operator key issued by Trueplay to access the API |

#### Request Body

| Name                                                     | Type           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| operatorUserId<mark style="color:red;">\*</mark>         | String         | ID of the user on the operator’s side                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| transactionId<mark style="color:red;">\*</mark>          | String         | Unique identifier for the transaction (BET, WIN, ROLLBACK)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| referenceTransactionId<mark style="color:red;">\*</mark> | String \| null | <p>Used to link related transactions.</p><p>• For BET transactions, this will be null as they are the starting point of the sequence.</p><p>• For WIN transactions, this field should reference the transactionId of the corresponding BET.</p><p>• For ROLLBACK transactions, this field should reference the transactionId of the original BET being rolled back. This also applies to rolling back WIN transactions; the referenceTransactionId should point to the transactionId of the WIN being rolled back.</p> |
| type<mark style="color:red;">\*</mark>                   | String         | Transaction type: BET, WIN, or ROLLBACK                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| gameProvider<mark style="color:red;">\*</mark>           | String         | Game provider name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| gamePublisher<mark style="color:red;">\*</mark>          | String         | Game publisher name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| gameCode<mark style="color:red;">\*</mark>               | String         | Game code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| gameName<mark style="color:red;">\*</mark>               | String         | Game name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| gameType<mark style="color:red;">\*</mark>               | String         | Type of game (e.g., Slots, Sportsbook)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| currency<mark style="color:red;">\*</mark>               | String         | ISO currency code (e.g., USDT, USD)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| amount<mark style="color:red;">\*</mark>                 | Integer        | <p>Transaction amount. </p><p>Up to 2 decimals for fiat, 8 for crypto</p>                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| customFields                                             | Object (Map)   | *Optional.* A key-value map of custom metadata fields for mission logic                                                                                                                                                                                                                                                                                                                                                                                                                                                |

**Important**: Ensure that referenceTransactionId correctly links to the associated BET or BONUS\_BET, or WIN or BONUS\_WIN as applicable. Setting it to 0 or leaving it blank when it should be populated will result in errors and incorrect transaction processing.

**Request example**

{% tabs %}
{% tab title="Request example (BET)" %}

```
Request
curl --location 'https://{operator-name}.proxy.trueplay.io/api/v1/accept' 
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key-here' \
--data '{
    "userId": "1",
    "transactionId": "12345",
    "type": "WIN",
    "gameProvider": "NOLIMIT_CITY",
    "gamePublisher": "EVOLUTION",
    "gameCode": "Mental",
    "gameName": "Mental",
    "gameType": "Slots",
    "currency": "USDT",
    "amount": 25.00000000,
}
```

{% endtab %}

{% tab title="Request example (WIN)" %}

```
Request
curl --location 'https://{operator-name}.proxy.trueplay.io/api/v1/accept' 
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key-here' \
--data '{
    "userId": "1",
    "transactionId": "5678",
    "type": "WIN",
    "gameProvider": "NOLIMIT_CITY",
    "gamePublisher": "EVOLUTION",
    "gameCode": "Mental",
    "gameName": "Mental",
    "gameType": "Slots",
    "currency": "USDT",
    "amount": 50.00000000,
}'
```

{% endtab %}

{% tab title="Request example (ROLLBACK BET)" %}

```
Request
curl --location 'https://{operator-name}.proxy.trueplay.io/api/v1/accept' 
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key-here' \
--data '{
    "userId": "1",
    "transactionId": "54321",
    "type": "ROLLBACK",
    "gameProvider": "NOLIMIT_CITY",
    "gamePublisher": "EVOLUTION",
    "gameCode": "Mental",
    "gameName": "Mental",
    "gameType": "Slots",
    "currency": "USDT",
    "amount": 25.00000000,
    "referenceTransactionId": "12345"
}'
```

{% endtab %}

{% tab title="Request example (ROLLBACK WIN)" %}

```
Request
curl --location 'https://{operator-name}.proxy.trueplay.io/api/v1/accept' 
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key-here' \
--data '{
    "userId": "1",
    "transactionId": "43210",
    "type": "ROLLBACK",
    "gameProvider": "NOLIMIT_CITY",
    "gamePublisher": "EVOLUTION",
    "gameCode": "Mental",
    "gameName": "Mental",
    "gameType": "Slots",
    "currency": "USDT",
    "amount": 50.00000000,
    "referenceTransactionId": "5678"
}'
```

{% endtab %}
{% endtabs %}

**Response example**

{% tabs %}
{% tab title="200: OK Request is successful" %}

```
200 OK
```

{% endtab %}

{% tab title="400: Bad Request " %}

```
400 Bad Request
```

{% endtab %}
{% endtabs %}

## Operator endpoints <a href="#operator-endpoints" id="operator-endpoints"></a>

### Get User Balance

<mark style="color:green;">`POST`</mark>&#x20;

`https://{operatorBaseUrl}/user-balance`

**Method Description:** This method allows retrieving the current balance of a user in a casino. Operators must provide the user's unique identifier on their side, and upon successful authentication, the method returns the user's balance along with the currency in which it is denominated.&#x20;

**This method is necessary to implement the token exchange endpoints.**

#### Headers

| Name                                                  | Type   | Description                                                                    |
| ----------------------------------------------------- | ------ | ------------------------------------------------------------------------------ |
| X-REQUEST-SIGNATURE<mark style="color:red;">\*</mark> | String | <p>Request signature, Base64(HmacSHA512(SecretKey, MD5(request body)))<br></p> |

#### Request Body

| Name                                             | Type   | Description                 |
| ------------------------------------------------ | ------ | --------------------------- |
| operatorUserId<mark style="color:red;">\*</mark> | String | ID of user on Operator side |

{% tabs %}
{% tab title="200: OK Request is sucessful" %}
{% code fullWidth="true" %}

```json
 {
 "balance": 100.12,
 "currency": "USD"
 }
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Token Exchange

<mark style="color:green;">`POST`</mark>&#x20;

`https://{operatorBaseUrl}/token-exchange`

**Method Description:** This method enables users to deposit tokens using funds from the casino balance or withdraw tokens to the casino balance. It supports two actions: CREDIT and DEBIT.

* **CREDIT:** Withdraws tokens from the loyalty page balance and converts them into money, adding them to the casino balance.
* **DEBIT:** Deposits money from the casino balance and converts it into tokens, adding them to the loyalty page balance.

To integrate Token Exchange endpoints successfully, operators must specify the Callback URL from which deposit/withdrawal requests will be executed and generate transaction signatures using the Secret Key, which should be included in the request header. Correct transaction types (CREDIT or DEBIT) must be provided in the request body for the method to function accurately.

#### Headers

<table><thead><tr><th width="250">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>X-REQUEST-SIGNATURE<mark style="color:red;">*</mark></td><td>String</td><td>Request signature, Base64(HmacSHA512(SecretKey, MD5(request body)))</td></tr></tbody></table>

#### Request Body

| Name                                             | Type    | Description                                                                                                                                                                                               |
| ------------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id<mark style="color:red;">\*</mark>             | String  | operation ID                                                                                                                                                                                              |
| action<mark style="color:red;">\*</mark>         | String  | Specifies the action to be performed. Accepted values are CREDIT (transfer from token balance to operator account balance) and DEBIT (transfer from operator account balance to token balance)            |
| amount<mark style="color:red;">\*</mark>         | Integer | <p></p><ul><li>Fiat: Although fiat currencies typically allow up to two decimal places (e.g., USD: 10.25)</li><li>Cryptocurrency: The amount parameter adheres to a maximum of 8 decimal places</li></ul> |
| currency                                         | String  | Currency code used in the transaction                                                                                                                                                                     |
| tokenAmount<mark style="color:red;">\*</mark>    | Integer | Token amount involved in the transaction                                                                                                                                                                  |
| operatorId<mark style="color:red;">\*</mark>     | String  | ID of Operator                                                                                                                                                                                            |
| operatorUserId<mark style="color:red;">\*</mark> | String  | ID of user on Operator side                                                                                                                                                                               |

{% tabs %}
{% tab title="200: OK Request is succesful" %}

```json
{
"balance": 100.12,
"currency": "USD"
}
```

{% endtab %}

{% tab title="400: Deposit is failed" %}

{% endtab %}

{% tab title="403: User has a bonus balance" %}

{% endtab %}
{% endtabs %}

## Request signature

Requests from TruePlay include `X-REQUEST-SIGNATURE` header.

Example of how to generate a signature for SecretKey = `secret`

> node \
> \
> Welcome to Node.js v16.13.0. Type ".help" for more information.\
> \
> var crypto = require('crypto'); \
> undefined \
> \
> var hasher = crypto.createHash('md5'); \
> undefined \
> \
> var hashed = hasher.update('{"id":"103193","action":"CREDIT","amount":4.123,"currency":"USD","exchangeRate":0.00203250655485,"tokenAmount":2500,"operatorId":123,"operatorUserId":"333"}') \
> undefined\
> \
> var hash = hashed.digest('hex'); \
> undefined \
> \
> var hmac = crypto.createHmac('sha512', 'secret'); \
> undefined \
> \
> hmac.update(hash); \
> Hmac { \_options: undefined, \[Symbol(kHandle)]: Hmac {}, \[Symbol(kState)]: { \[Symbol(kFinalized)]: false } } \
> \
> var sign = hmac.digest('base64'); \
> undefined \
> \
> console.log('signature: ' + sign); \
> signature: IifPVbfXptagZ6qSXH9vYrQiqSP4sKIC+hV+39z2K+FlLzRoEboPGTTymjmeuAhN1i0ICDyyrrufYspgAJmxHQ==

## Marketing Campaigns

### Create user account

<mark style="color:green;">`POST`</mark>&#x20;

`https://integration.trueplay.io/api/v1/user`

Create user on Trueplay side to get promo reward.  &#x20;

#### Headers

| Name                                        | Type   | Description                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------ |
| X-API-KEY<mark style="color:red;">\*</mark> | String | Operator key issued by TruePlay to access TruePlay API |

#### Request Body

<table><thead><tr><th width="283">Name</th><th width="212">Type</th><th>Description</th></tr></thead><tbody><tr><td>kyc</td><td>String</td><td>Indicates whether the user has passed the KYC verification process. When <strong>true</strong>, the user has successfully completed the KYC process; when <strong>false</strong>, the user has not yet completed KYC.</td></tr><tr><td>operatorUserId<mark style="color:red;">*</mark></td><td>String</td><td>ID of user on Operator side</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK Request is successful" %}

```
"operatorUserId": "john12345"
```

{% endtab %}
{% endtabs %}

### Update user account

<mark style="color:orange;">`PUT`</mark>&#x20;

`https://integration.trueplay.io/api/v1/user`

The method to update user's "Kyc" parameter to get promo reward.

#### Headers

| Name                                        | Type   | Description                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------ |
| X-API-KEY<mark style="color:red;">\*</mark> | String | Operator key issued by TruePlay to access TruePlay API |

#### Request Body

<table><thead><tr><th width="283">Name</th><th width="212">Type</th><th>Description</th></tr></thead><tbody><tr><td>kyc</td><td>String</td><td>Indicates whether the user has passed the KYC verification process. When <strong>true</strong>, the user has successfully completed the KYC process; when <strong>false</strong>, the user has not yet completed KYC.</td></tr><tr><td>operatorUserId<mark style="color:red;">*</mark></td><td>String</td><td>ID of user on Operator side</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK Request is successful" %}

```json
{
"kyc": true,
"operatorUserId": "22334455"
}
```

{% endtab %}
{% endtabs %}

### Send user deposit&#x20;

<mark style="color:green;">`POST`</mark>&#x20;

`https://integration.trueplay.io/api/v1/promo/deposit`

This API method is used to process and register a user’s deposit within the casino platform. It ensures that the deposit is acknowledged within the Trueplay system and applies any promotional rewards associated with the deposit.

#### Request Body

| Name                                             | Type    | Description                                                                                                         |
| ------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- |
| transactionId<mark style="color:red;">\*</mark>  | String  | A unique transaction identifier used for tracking the operation.                                                    |
| operatorUserId<mark style="color:red;">\*</mark> | String  | The user’s identifier in the operator’s system.                                                                     |
| amount<mark style="color:red;">\*</mark>         | Integer | The deposit amount in the currency specified in the currency parameter.                                             |
| currency<mark style="color:red;">\*</mark>       | String  | Currency code following the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard (e.g., EUR, USD). |
| amountUsd<mark style="color:red;">\*</mark>      | Integer | The equivalent deposit amount in US dollars (USD), based on the current exchange rate.                              |
| createdAt<mark style="color:red;">\*</mark>      | String  | The transaction creation date and time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.SSS).                                |

{% tabs %}
{% tab title="Request example" %}

```
Request
curl --location 'https://integration.trueplay.io/api/v1/promo/deposit' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key-here' \
--data '{
    "transactionId": "230821765",
    "operatorUserId": "331438",
    "amount": "28.00",
    "currency": "EUR",
    "amountUsd": 29.008000000000003,
    "createdAt": "2025-02-12T21:36:47.000"
}'
```

{% endtab %}

{% tab title="Response example" %}
200: OK Request is successful
{% endtab %}
{% endtabs %}

The operator can also define a user segment to add to the campaign using API.  The Marketing Campaigns API supports the following methods

### Get all Active marketing campaigns

<mark style="color:blue;">`GET`</mark>&#x20;

`https://integration.trueplay.io/api/v1/promo-campaign/active`

The method returns a list of active marketing campaigns. This must be performed before adding a user to the campaign, so as to avoid adding a user to a campaign with the Draft/Expired/Deactivated status by accident.

#### Headers

| Name                                        | Type   | Description                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------ |
| X-Api-KEY<mark style="color:red;">\*</mark> | String | Operator key issued by TruePlay to access TruePlay API |

{% tabs %}
{% tab title="200: OK Request is successful" %}

```json
 {
      "accrualCondition": "string",
      "allUsers": true,
      "betVolumeRule": 0,
      "cashbackTime": 0,
      "conditionMax": 0,
      "conditionMin": 0,
      "createdAt": "2023-09-22T15:50:22.909",
      "dailyCashbackReward": 0,
      "dailyCashbackRewardAmount": 0,
      "dayOfWeek": "string",
      "duration": 0,
      "expirationDate": "2023-09-22",
      "fixedAmountReward": 0,
      "id": 0,
      "kycRule": true,
      "maxUserCount": 0,
      "name": "string",
      "p2eMultiplierReward": 0,
      "participants": 0,
      "percentAmountReward": 0,
      "registeredAfter": "2023-09-22",
      "signUpRule": true,
      "stakingLimitCoefficientReward": 0,
      "status": "string",
      "sumFixedAmountReward": 0,
      "weeklyCashbackReward": 0,
      "weeklyCashbackTime": 0
    }
    
    
```

{% endtab %}
{% endtabs %}

### Get marketing campaign participants by campaign ID

<mark style="color:blue;">`GET`</mark>&#x20;

`https://integration.trueplay.io/api/v1/promo-campaign/{campaign_id}/participants`

Returns a list of marketing campaign participants

#### Path Parameters

| Name                                 | Type    | Description              |
| ------------------------------------ | ------- | ------------------------ |
| id<mark style="color:red;">\*</mark> | Integer | ID of marketing campaign |

#### Headers

| Name                                        | Type   | Description                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------ |
| X-API-KEY<mark style="color:red;">\*</mark> | String | Operator key issued by TruePlay to access TruePlay API |

{% tabs %}
{% tab title="200: OK Request is succesful" %}

```json
{ 
  "content": [ 
    { 
      "campingId": 10, 
      "createdAt": "2023-04-20T09:15:40.545", 
      "method": "API", 
      "operatorUserId": "23423", 
    },
  ]
    { 
      "campingId": 15, 
      "createdAt": "2023-04-20T09:15:40.545", 
      "method": "Manual", 
      "operatorUserId": "97500", 
    },            
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid request parameters provided" %}

{% endtab %}

{% tab title="401: Unauthorized Requester is unauthorized to perform an action" %}

{% endtab %}

{% tab title="403: Forbidden Requester is forbidden to perform an action" %}

{% endtab %}

{% tab title="404: Not Found Resource not found" %}

{% endtab %}
{% endtabs %}

### Assign user to the marketing campaign

<mark style="color:green;">`POST`</mark>&#x20;

`https://integration.trueplay.io/api/v1/promo-campaign/{campaignId}/user/{operatorUserId}`

The method add a user to the marketing campaign

#### Path Parameters

| Name                                             | Type    | Description                 |
| ------------------------------------------------ | ------- | --------------------------- |
| operatorUserId<mark style="color:red;">\*</mark> | Integer | ID of user on Operator side |
| campaignId<mark style="color:red;">\*</mark>     | Integer | ID of marketing campaign    |

#### Headers

| Name                                        | Type   | Description                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------ |
| X-Api-Key<mark style="color:red;">\*</mark> | String | Operator key issued by TruePlay to access TruePlay API |

{% tabs %}
{% tab title="201: Created Request is succesful" %}

```json
{
  "campingId": 0,
  "createdAt": "2023-09-22T16:11:42.371",
  "method": "string",
  "operatorUserId": "string",
  "transaction": "string"
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid request parameters provided" %}

{% endtab %}

{% tab title="401 Requester is unauthorized to perform an action" %}

{% endtab %}

{% tab title="403: Forbidden Requester is forbidden to perform an action" %}

{% endtab %}

{% tab title="404: Not Found Resource not found" %}

{% endtab %}
{% endtabs %}

### Delete user from marketing campaign

<mark style="color:red;">`DELETE`</mark>&#x20;

`https://integration.trueplay.io/api/v1/promo-campaign/{campaignId}/user/{operatorUserId}`

The method delete users from marketing campaign

#### Path Parameters

| Name                                             | Type    | Description                 |
| ------------------------------------------------ | ------- | --------------------------- |
| campaignId<mark style="color:red;">\*</mark>     | Integer | ID of marketing campaign    |
| operatorUserId<mark style="color:red;">\*</mark> | Integer | ID of user on Operator side |

#### Headers

| Name                                        | Type   | Description                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------ |
| X-API-KEY<mark style="color:red;">\*</mark> | String | Operator key issued by TruePlay to access TruePlay API |

{% tabs %}
{% tab title="200: OK Request is succesful" %}

{% endtab %}
{% endtabs %}

## Users Rewards

### Get the total amount of rewards for all users

<mark style="color:blue;">`GET`</mark>&#x20;

`https://integration.trueplay.io/api/v1/operator/rewards`

The method returns a list of all types of rewards by all users.  It is possible to set a time interval for receiving a list of rewards

#### Query Parameters

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| startDate<mark style="color:red;">\*</mark> | String |             |
| endDate<mark style="color:red;">\*</mark>   | String |             |

#### Headers

| Name                                        | Type   | Description                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------ |
| X-API-KEY<mark style="color:red;">\*</mark> | String | Operator key issued by TruePlay to access TruePlay API |

#### Response

{% tabs %}
{% tab title="200: OK Request is succesfull" %}

```json
 {
  "playToEarn": 0,
  "holdToEarn": 0,
  "promo": 0,
  "dailyCashback": 0,
  "weeklyCashback": 0,
  "referralPlayToEarn": 0,
  "referralHoldToEarn": 0,
  "playToEarnRollback": 0,
  "burn": 0
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid request parameters provided" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="401: Unauthorized Requester is unauthorized to perform an action" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="403: Forbidden Requester is forbidden to perform an action" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="404: Not Found Resource not found" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

### Get the amount of rewards separately for each user

<mark style="color:blue;">`GET`</mark>&#x20;

`https://integration.trueplay.io/api/v1/users/rewards`

The method returns a list of users and their awards for a certain period of time. \
Maximum time period - 24 hours. \
The request must indicate the from (date and time) - to (date and time).   \
\
For example, a request for a period 2024-03-24 13:00:00.000 - 2024-03-24 14:00:00.000 will return a list of users and their rewards for the specified period.

#### Query Parameters

| Name                                   | Type   | Example                 |
| -------------------------------------- | ------ | ----------------------- |
| from<mark style="color:red;">\*</mark> | String | 2024-04-01 00:00:00.000 |
| to<mark style="color:red;">\*</mark>   | String | 2024-04-02 00:00:00.000 |

#### Headers

| Name                                        | Type   | Description                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------ |
| X-API-KEY<mark style="color:red;">\*</mark> | String | Operator key issued by TruePlay to access TruePlay API |

#### Response

{% tabs %}
{% tab title="200: OK Request is succesfull" %}

```json
[
  {
    "playToEarnRollback": null,
    "casinoReward": null,
    "promo": null,
    "dailyCashback": null,
    "weeklyCashback": null,
    "burn": null,
    "playToEarn": 10.35,
    "holdToEarn": null,
    "operatorUserId": "0026337c1-9d39-43a7-a734-d60dd94z1bf2"
  },
  {
    "playToEarnRollback": null,
    "casinoReward": null,
    "promo": null,
    "dailyCashback": null,
    "weeklyCashback": null,
    "burn": null,
    "playToEarn": null,
    "holdToEarn": 0.7060225419336147,
    "operatorUserId": "0vb6376b5-6ddc-4156-8bba-b81df693d8dc"
  }
 ] 
```

{% endtab %}

{% tab title="400: Bad Request Invalid request parameters provided" %}
`{`&#x20;

`}`
{% endtab %}

{% tab title="401: Unauthorized Requester is unauthorized to perform an action" %}

{% endtab %}

{% tab title="403: Forbidden Requester is forbidden to perform an actiontitled" %}

{% endtab %}

{% tab title="404: Not Found Resource not found" %}

{% endtab %}
{% endtabs %}

### Get a reward by a user

<mark style="color:blue;">`GET`</mark> `https://integration.trueplay.io/api/v1/user/${operatorUserId}/rewards`

The method returns a list of all types of rewards by a specific user.  It is possible to set a time interval for receiving a list of rewards

#### Path Parameters

| Name                                             | Type   | Description                 |
| ------------------------------------------------ | ------ | --------------------------- |
| operatorUserId<mark style="color:red;">\*</mark> | String | ID of user on Operator side |

#### Query Parameters

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| startDate | String |             |
| endDate   | String |             |

#### Headers

| Name                                        | Type   | Description                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------ |
| X-API-KEY<mark style="color:red;">\*</mark> | String | Operator key issued by TruePlay to access TruePlay API |

#### Response

{% tabs %}
{% tab title="200: OK Request is succesful" %}

```json
 {
  "playToEarn": 0,
  "holdToEarn": 0,
  "promo": 0,
  "dailyCashback": 0,
  "weeklyCashback": 0,
  "referralPlayToEarn": 0,
  "referralHoldToEarn": 0,
  "playToEarnRollback": 0,
  "burn": 0
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid request parameters provided" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="401: Unauthorized Requester is unauthorized to perform an action" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="403: Forbidden Requester is forbidden to perform an action" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="404: Not Found Resource not found" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

### Check user balance

<mark style="color:blue;">`GET`</mark> `https://integration.trueplay.io/api/v1/user/{operatorUserId}/check-balance`

The method returns 2 values by selected user :&#x20;

* The total amount of tokens on the user's wallet ;
* The total amount of tokens in Hold To Earn programs .

The rate limit is 60 requests per minute.

#### Path Parameters

| Name                                             | Type   | Description                 |
| ------------------------------------------------ | ------ | --------------------------- |
| operatorUserId<mark style="color:red;">\*</mark> | String | ID of user on Operator side |

#### Headers

| Name                                        | Type   | Description                                            |
| ------------------------------------------- | ------ | ------------------------------------------------------ |
| X-API-KEY<mark style="color:red;">\*</mark> | String | Operator key issued by TruePlay to access TruePlay API |

#### Response

{% tabs %}
{% tab title="200: OK Request is succesful" %}

```
{ 
"balance": 100.5, 
"balanceH2e": 20000.5 
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid request parameters provided" %}

```
{
    // Response
}
```

{% endtab %}
{% endtabs %}

### Accrual of rewards for activity in the casino

<mark style="color:green;">`POST`</mark>&#x20;

`https://integration.trueplay.io/api/v1/casino/reward`

This method is used when a user on the casino side reaches a specific level that triggers a token reward.\
The operator can award tokens to users once they complete the following actions:

* When the user reaches a certain level of play ;
* For tournament participation ;
* When the user opens loot boxes ;
* Other triggers.

**Headers**

<table><thead><tr><th width="234">Name</th><th width="224">Type</th><th>Description</th></tr></thead><tbody><tr><td>X-API-KEY<mark style="color:red;">*</mark></td><td>String</td><td>Operator key issued by TruePlay to access TruePlay API</td></tr></tbody></table>

**Body**

<table><thead><tr><th width="230">Name</th><th width="245">Type</th><th>Description</th></tr></thead><tbody><tr><td>operatorUserId</td><td>string</td><td>ID of user on Operator side<br></td></tr><tr><td>amount</td><td>Integer</td><td>The number of tokens that must be credited to the user's loyalty page balance</td></tr><tr><td>requestId</td><td>string</td><td></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "operatorUserId": "john12345",
  "amount": 3.56,
  "requestId": "string"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

### Swap loyalty balance to the bonus balance in the casino

<mark style="color:green;">`POST`</mark>&#x20;

`https://integration.trueplay.io/api/v1/casino/loyalty-swap`

This method is used when the operator allow the user to withdraw tokens from the loyalty page and receive a bonus balance, freespins or freebets. The operator should add a pop-up, button, etc where the user see the ratio of the number of tokens to the number of freespins (freebets)

**Headers**

<table><thead><tr><th width="234">Name</th><th width="224">Type</th><th>Description</th></tr></thead><tbody><tr><td>X-API-KEY<mark style="color:red;">*</mark></td><td>String</td><td>Operator key issued by TruePlay to access TruePlay API</td></tr></tbody></table>

**Body**

<table><thead><tr><th width="230">Name</th><th width="232">Type</th><th>Description</th></tr></thead><tbody><tr><td>operatorUserId</td><td>string</td><td>ID of user on Operator side<br></td></tr><tr><td>amount</td><td>Integer</td><td>The number of tokens that must be withdrawn from user's loyalty page balance</td></tr><tr><td>requestId</td><td>string</td><td></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200: OK Request is successful" %}

{% endtab %}

{% tab title="400" %}

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.trueplay.io/tech/loyalty-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.