Integration for the operator

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: (link).

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

The method to get link on loyalty page to open in iframe into Casino.

Path Parameters

Name	Type	Description
operatorUserId*	String	ID of user on Operator side

Query Parameters

Name	Type	Description
language*	String	Localization of user loyalty page Default language of loyalty page: ENG Available languages: CS, DE, ES, FR, HU, ID, JA, LT, LV, PL, PT, BN, RU, SK, TR, BN
view	String	Allows to open the required view of the loyalty page. Available view: account, analytics, deposit, withdraw, token-sale, stream

Headers

Name	Type	Description
X-API-KEY*	String	Operator key issued by TruePlay to access TruePlay API

200: OK Request is succesful

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

400: Bad Request Invalid request parameters provided

401: Unauthorized Requester is unauthorized to perform an action

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

403: Forbidden Requester is forbidden to perform an action

404: Not Found Resource not found

Anonymous user

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

The method to get link on loyalty page to open in iframe into Casino.

Headers

Name	Type	Description
X-API-KEY*	String	Operator key issued by TruePlay to access TruePlay API

200: OK Request is succesful

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

400: Bad Request Invalid request parameters provided

401: Unauthorized Requester is unauthorized to perform an action

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

403: Forbidden Requester is forbidden to perform an action

404: Not Found Resource not found

Get user balance

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

The method to get the user's balance on the loyalty page. The operator can show this balance in the casino.

Path Parameters

Name	Type	Description
operatorUserId*	String	ID of user on Operator side

Headers

Name	Type	Description
X-API-KEY*	String	Operator key issued by TruePlay to access TruePlay API

200: OK Request is sucessful

{
  "balance": 0.0001
}

400: Bad Request Invalid request parameters provided

Untitled

401: Unauthorized Requester is unauthorized to perform an action

403: Forbidden Requester is forbidden to perform an action

404 Resource not found

Send game transaction

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

The method to send game traffic from operator to Trueplay.

Headers

Name	Type	Description
X-API-KEY*	String	Operator key issued by TruePlay to access TruePlay API

Request Body

Name	Type	Description
operatorUserId*	String	ID of user on Operator side
transactionId*	String
referenceTransactionId*	String	Id of game transactions (BET | WIN) . This is required to be sent for such types of game transactions as ( REFUND | ROLLBACK )
type*	String	Type of game transaction (BET | WIN | ROLLBACK | BONUS_BET | BONUS_WIN)
gameProvider	String
gameCode*	String
gameName*	String
gameType*	String
currency*	String
amount*	Integer

Operator endpoints

Get User Balance

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

The method to get the user's balance in a casino

Headers

Name	Type	Description
X-REQUEST-SIGNATURE*	String	Request signature, Base64(HmacSHA512(SecretKey, MD5(request body)))

Request Body

Name	Type	Description
operatorUserId*	String	ID of user on Operator side

200: OK Request is sucessful

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

Token Exchange

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

The method consists of two actions: 1. CREDIT - withdrawals of token from loyalty page balance and conversion of tokens into money to the casino balance 2. DEBIT - deposit of money from casino balance and conversion of money into tokens to the loyalty page balance

Headers

Name	Type	Description
X-REQUEST-SIGNATURE*	String	Request signature, Base64(HmacSHA512(SecretKey, MD5(request body)))

Request Body

Name	Type	Description
id*	String	operation ID
action*	String	CREDIT - Transfer from token balance to operator account balance DEBIT - Transfer operator account balance to token balance
amount*	Integer
currency	String
exchangeRate*	Integer
tokenAmount*	Integer
operatorId*	String
operatorUserId*	String	ID of user on Operator side

200: OK Request is succesful

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

400: Deposit is failed

403: User has a bonus balance

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

Name	Type	Description
X-API-KEY*	String	Operator key issued by TruePlay to access TruePlay API

Request Body

Name	Type	Description
operatorUserId*	String	ID of user on Operator side

200: OK Request is successful

"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

Name	Type	Description
X-API-KEY*	String	Operator key issued by TruePlay to access TruePlay API

Request Body

Name	Type	Description
kyc*	String
operatorUserId*	String	ID of user on Operator side

200: OK Request is successful

{
"operatorUserId": "john12345"
}

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

Name	Type	Description
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

201: Created Request is successful

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

Name	Type	Description
X-Api-KEY*	String	Operator key issued by TruePlay to access TruePlay API

200: OK Request is successful

 {
      "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

Name	Type	Description
id*	Integer	ID of marketing campaign

Headers

Name	Type	Description
X-API-KEY*	String	Operator key issued by TruePlay to access TruePlay API

200: OK Request is succesful

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

400: Bad Request Invalid request parameters provided

401: Unauthorized Requester is unauthorized to perform an action

403: Forbidden Requester is forbidden to perform an action

404: Not Found Resource not found

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

Name	Type	Description
operatorUserId*	Integer	ID of user on Operator side
campaignId*	Integer	ID of marketing campaign

Headers

Name	Type	Description
X-Api-Key*	String	Operator key issued by TruePlay to access TruePlay API

201: Created Request is succesful

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

400: Bad Request Invalid request parameters provided

401 Requester is unauthorized to perform an action

403: Forbidden Requester is forbidden to perform an action

404: Not Found Resource not found

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

Name	Type	Description
campaignId*	Integer	ID of marketing campaign
operatorUserId*	Integer	ID of user on Operator side

Headers

Name	Type	Description
X-API-KEY*	String	Operator key issued by TruePlay to access TruePlay API

200: OK Request is succesful

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

Name	Type	Description
startDate*	String
endDate*	String

Headers

Name	Type	Description
X-API-KEY*	String	Operator key issued by TruePlay to access TruePlay API

Response

200: OK Request is succesfull

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

400: Bad Request Invalid request parameters provided

{
    // Response
}

401: Unauthorized Requester is unauthorized to perform an action

{
    // Response
}

403: Forbidden Requester is forbidden to perform an action

{
    // Response
}

404: Not Found Resource not found

{
    // Response
}

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

Name	Type	Example
from*	String	2024-04-01 00:00:00.000
to*	String	2024-04-02 00:00:00.000

Headers

Name	Type	Description
X-API-KEY*	String	Operator key issued by TruePlay to access TruePlay API

Response

200: OK Request is succesfull

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

400: Bad Request Invalid request parameters provided

{

}

401: Unauthorized Requester is unauthorized to perform an action

403: Forbidden Requester is forbidden to perform an actiontitled

404: Not Found Resource not found

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

Name	Type	Description
operatorUserId*	String	ID of user on Operator side

Query Parameters

Name	Type	Description
startDate	String
endDate	String

Headers

Name	Type	Description
X-API-KEY*	String	Operator key issued by TruePlay to access TruePlay API

200: OK Request is succesful

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

400: Bad Request Invalid request parameters provided

{
    // Response
}

401: Unauthorized Requester is unauthorized to perform an action

{
    // Response
}

403: Forbidden Requester is forbidden to perform an action

{
    // Response
}

404: Not Found Resource not found

{
    // Response
}

Accrual of rewards for activity in the casino

Accrual reward for a user

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

Name	Type	Description
X-API-KEY*	String	Operator key issued by TruePlay to access TruePlay API

Body

Name	Type	Description
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

200

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

400

{
  "error": "Invalid request"
}

Swap loyalty balance to the bonus balance in the casino

Loyalty Swap for a user

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

Name	Type	Description
X-API-KEY*	String	Operator key issued by TruePlay to access TruePlay API

Body

Name	Type	Description
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

200: OK Request is successful

400