Loyalty Integration

Component diagram

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:

  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.

IPs for whitelisting

18.193.249.95

18.184.86.250

18.196.113.251

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

Get Loyalty page

Authorized user

GET 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

NameTypeDescription

operatorUserId*

String

ID of user on Operator side

Query Parameters

NameTypeDescription

language*

String

Localization of user loyalty page Default language of loyalty page: EN

Available languages: BN, CS, DE, EN, ES, FR, HU, ID, JA, LT, LV, PL, PT, RU, SK, TR

view

String

Allows to open the required view of the loyalty page. Available view: account, analytics, deposit, withdraw, token-sale, stream

Headers

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

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

Anonymous user

GET

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

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

Example response

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

Get transaction data

Get user loyalty balance

GET 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

NameTypeDescription

operatorUserId*

String

ID of user on Operator side

Headers

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

Example:

{
  "balance": 0.0001
}

Send game transaction

POST

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

Method Description: This method allows operators to send game transaction data to Trueplay. Operators must provide the relevant details of each transaction.

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

IMPORTANT! For correct calculation of rewards, it is necessary to indicate correct types of transactions:

  • BET, WIN - game actions

  • ROLLBACK - cancellation of BET or WIN transaction

  • BONUS_BET - a bet using bonus funds

  • BONUS_WIN - winning using bonus funds

Particularities of data transmission:

  • In the case of mixed balance bets (part of the funds comes from the real balance, part of the funds comes from bonus balance) - it is necessary to send 2 separate bets BET/WIN and BONUS_BET/BONUS_WIN respectively.

  • 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

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

Request Body

NameTypeDescription

operatorUserId*

String

ID of user on Operator side

transactionId*

String

A unique identifier for each transaction type (BET, WIN, ROLLBACK, BONUS_BET, BONUS_WIN). For every new action (BET, WIN, ROLLBACK, BONUS_BET, BONUS_WIN) a distinct transactionId is generated to track that specific action.

referenceTransactionId*

String

Used to link related transactions.

• For BET and BONUS_BET transactions, this will be null as they are the starting point of the sequence.

• For WIN and BONUS_WIN transactions, this field should reference the transactionId of the corresponding BET or BONUS_BET.

• For ROLLBACK transactions, this field should reference the transactionId of the original BET or BONUS_BET being rolled back. This also applies to rolling back WIN or BONUS_WIN transactions; the referenceTransactionId should point to the transactionId of the WIN or BONUS_WIN being rolled back.

type*

String

Type of game transaction (BET | WIN | ROLLBACK | BONUS_BET | BONUS_WIN)

gameProvider*

String

Indicates the provider of the game or platform associated with the transaction

gamePublisher*

String

Specifies the game’s publisher

gameCode*

String

Code of the game

gameName*

String

An identifier for the specific game associated with the transaction

gameType*

String

Type of the game

currency*

String

Currency code used in the transaction

amount*

Integer

Amount involved in the transaction

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

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,
}

Response example

200 OK

Operator endpoints

Get User Balance

POST

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.

This method is necessary to implement the token exchange endpoints.

Headers

NameTypeDescription

X-REQUEST-SIGNATURE*

String

Request signature, Base64(HmacSHA512(SecretKey, MD5(request body)))

Request Body

NameTypeDescription

operatorUserId*

String

ID of user on Operator side

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

Token Exchange

POST

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

NameTypeDescription

X-REQUEST-SIGNATURE*

String

Request signature, Base64(HmacSHA512(SecretKey, MD5(request body)))

Request Body

NameTypeDescription

id*

String

operation ID

action*

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*

Integer

Amount involved in the transaction

currency

String

Currency code used in the transaction

tokenAmount*

Integer

Token amount involved in the transaction

operatorId*

String

ID of Operator

operatorUserId*

String

ID of user on Operator side

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

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

POST

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

Create user on Trueplay side to get promo reward.

Headers

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

Request Body

NameTypeDescription

kyc

String

Indicates whether the user has passed the KYC verification process. When true, the user has successfully completed the KYC process; when false, the user has not yet completed KYC.

operatorUserId*

String

ID of user on Operator side

"operatorUserId": "john12345"

Update user account

PUT

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

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

Headers

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

Request Body

NameTypeDescription

kyc

String

Indicates whether the user has passed the KYC verification process. When true, the user has successfully completed the KYC process; when false, the user has not yet completed KYC.

operatorUserId*

String

ID of user on Operator side

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

Send user deposit

POST

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

The method to get reward regarding the user's deposit on casino.

Request Body

NameTypeDescription

transactionId*

String

ID of transaction

operatorUserId*

String

ID of user on Operator side

amount*

Integer

Deposit amount in Operator currency

currency*

String

Currency of Operator

amountUsd*

Integer

Amount of deposit in USD

createdAt*

String

Deposit date

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

GET

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

NameTypeDescription

X-Api-KEY*

String

Operator key issued by TruePlay to access TruePlay API

 {
      "accrualCondition": "string",
      "allUsers": true,
      "betVolumeRule": 0,
      "cashbackTime": 0,
      "conditionMax": 0,
      "conditionMin": 0,
      "createdAt": "2023-09-22T15:50:22.909Z",
      "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
    }
    
    

Get marketing campaign participants by campaign ID

GET

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

Returns a list of marketing campaign participants

Path Parameters

NameTypeDescription

id*

Integer

ID of marketing campaign

Headers

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

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

Assign user to the marketing campaign

POST

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

The method add a user to the marketing campaign

Path Parameters

NameTypeDescription

operatorUserId*

Integer

ID of user on Operator side

campaignId*

Integer

ID of marketing campaign

Headers

NameTypeDescription

X-Api-Key*

String

Operator key issued by TruePlay to access TruePlay API

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

Delete user from marketing campaign

DELETE

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

The method delete users from marketing campaign

Path Parameters

NameTypeDescription

campaignId*

Integer

ID of marketing campaign

operatorUserId*

Integer

ID of user on Operator side

Headers

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

Users Rewards

Get the total amount of rewards for all users

GET

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

NameTypeDescription

startDate*

String

endDate*

String

Headers

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

Response

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

Get the amount of rewards separately for each user

GET

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

NameTypeExample

from*

String

2024-04-01 00:00:00.000

to*

String

2024-04-02 00:00:00.000

Headers

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

Response

[
  {
    "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"
  }
 ] 

Get a reward by a user

GET 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

NameTypeDescription

operatorUserId*

String

ID of user on Operator side

Query Parameters

NameTypeDescription

startDate

String

endDate

String

Headers

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

Response

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

Check user balance

GET https://integration.trueplay.io/api/v1/user/{operatorUserId}/check-balance

The method returns 2 values by selected user :

  • 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

NameTypeDescription

operatorUserId*

String

ID of user on Operator side

Headers

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

Response

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

Accrual of rewards for activity in the casino

POST

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

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

Body

NameTypeDescription

operatorUserId

string

ID of user on Operator side

amount

Integer

The number of tokens that must be credited to the user's loyalty page balance

requestId

string

Response

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

Swap loyalty balance to the bonus balance in the casino

POST

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

NameTypeDescription

X-API-KEY*

String

Operator key issued by TruePlay to access TruePlay API

Body

NameTypeDescription

operatorUserId

string

ID of user on Operator side

amount

Integer

The number of tokens that must be withdrawn from user's loyalty page balance

requestId

string

Response

Last updated