API Access Needed From Operator

Operators are required to provide specific endpoints to Gamanza Engagement Platform to facilitate the fundamental integration. Further details regarding these endpoints can be found below.

Integration

In order to provide a proper API integration, the Operators platform should provide endpoints requested by the Gamanza Engage Platform. The Gamanza Engage Platform supports the following authentication methods that should be implemented by the Operators platform:

• API Key
• OAuth2.0 client_credentials

The configuration options for these authentication methods are provided in the Admin website.

Flows:

1. The PEP authenticates with the Auth0 Operators Authorization Server using its Client ID and Client Secret ( /oauth/token endpoint).

2. Auth0 Operators Authorization Server validates the Client ID and Client Secret.

3. Auth0 Operators Authorization Server responds with an Access Token.

4. The PEP can use the access token to call an API on behalf of itself, using the x-authorization HTTP header.

5. The API responds with requested data.

Operators Platform API Authentication Config

To Register your platform authentication method into Gamanza Engage please follow the next steps:

1. Log in to your Admin Dashboard Instance and navigate to System Settings. Find the menu called Platform Integration, click on that and then find the Operators Platform API Authentication Config:

2. Update your configuration, by choosing the authentication method and add the required information. Two authentication methods are supported:

• API Key
• OAuth Client Credentials

And that's it!! Now the Gamanza Engage Platform can send requests to your Systems.

API Endpoints Required From Operator

The relevant endpoints for Operator API are:

Bonus Credit

The Operator needs to provide the Credit Bonus API endpoint to ensure Gamanza Engagement Platform can automate the bonus crediting.

The player should become eligible for the bonus immediately upon activation. However, whether the Operator is processing bonus interactions with their players will determine this.

tip

For more details check the Open API Specification here.

• Bonus Credit API Spec

To assign a bonus to players, please take into consideration that you as an operator need to validate this request as idempotent. We send a special property called eventDate and requestId to help you identify duplicate requests. For example, if your API returns an error (timeout, econnreset, rate-limit, 400, 500, etc), our platform performs a retry using a backoff mechanism and we send the entire request again until one of the following conditions are met:

1. The request succeeds
2. The max retry is reached -> the platform performs up to 5 retry operations

We always send the entire request back, and we expect you process the bonus in the background since this API expects a 202 status code (202 Accepted status code means that the request has been accepted for processing, but the processing has not been finished yet).

Here is some documentation about HTTP Status codes and their meaning: HTTP response status codes

Bonus List

To ensure a seamless experience for casino operators and marketing agents, you should provide a Bonus List and Filter API. Enabling this API allows bonuses to appear as user-friendly dropdowns within the platform, minimizing human error when configuring new rewards in PEP.

If you don't implement the Bonus List API, your Casino Operators will have to use a text input to add the Bonus Offer ID.

tip

For more details check the Open API Specification here.

• Get Bonuses

Important Considerations of the Bonus List Filters

The filter properties should support multiple values to accommodate integrations that require additional information. These filters enable the PEP Admin UI to display the appropriate options based on your integration’s specific requirements.

For customers that have a standard/simple bonus engine where only the name is required, the API requests the data based on simple filters like so:

HTTP GET: https://your-api.customer-server-domain.com/api/bonus/v1/get-bonus/all?page=1&perPage=10&filterBy=name&filterValue=BonusWelcome

Query Params	Value
page	1
perPage	10
filterBy	name
filterValue	BonusWelcome

When we need to pass extra filters, a common approach would be to allow multiple values for the filterBy and filterValue parameters, by using a list in the query string.

HTTP GET: /api/bonus/v1/get-bonus/all?page=1&perPage=10&filterBy[]=name&filterValue[]=BonusWelcome&filterBy[]=currency&filterValue[]=CRC

Query Params	Value
page	1
perPage	10
filterBy[]	name
filterBy[]	currency
filterValue[]	BonusWelcome
filterValue[]	CRC

In your backend side, depending on the framework you’re using, you would need to iterate through the query parameters and collect filterBy and filterValue pairs. In many web frameworks, query parameters with the same key can be handled as an array or list. For example:

filterBy[]=name&filterValue[]=BonusWelcome&filterBy[]=currency&filterValue[]=CRC

Building the query logic:

After capturing the filter criteria, you can then construct your database query or data filtering logic to apply each filter.

For example:

const filterBy = req.query.filterBy || [];
const filterValue = req.query.filterValue || [];

// Create an object to hold the filters
const filters = {};

for (let i = 0; i < filterBy.length; i++) {
  filters[filterBy[i]] = filterValue[i];
}

note

Please take into consideration that even if you support multiple filters; if in the request there is only one filter criteria, our system performs the request sending only one key and one value like so: filterBy=name&filterValue=BonusWelcome

Only if we detect an extra filter we send the request in array form: filterBy[]=name&filterValue[]=BonusWelcome&filterBy[]=currency&filterValue[]=CRC

This is to keep backward compatibility with existing integrations

Filters play a key role in enhancing the Admin UI, making it easier for your marketing team to work efficiently. At a minimum, the name filter must be implemented. Based on your integration requirements, you are responsible for adding any additional filters needed to support your use case.

Player Verify Session

One of the main and required endpoints is the Player Session Verification Process. As you can see in the intro section, our UI Widgets need to authenticate the players to secure the player requests from your Casino UI to our platform.

As we don't have access to validate or verify your players authentication, we depend on you to verify the current player session and its validity. This endpoint works as a "SSO", where you act as an Identity Provider.

Our widgets configuration requires something called an identity token. We need you to implement an API to receive this value and validate if the player has a valid and an active session. Once we receive your confirmation, adding the Player ID in response we can create our own authorization process.

tip

For more details check the Open API Specification here.

• Validate Player Identity Token

Check out our Widgets Client API Flow for more details.

This request is performed only once, the first time the Widgets are initialized in your Casino UI or when the session between the widgets and our server expires.

Reconciliation API

If you are using the CRM and by regulation there is information that your players need to meet for receiving Marketing campaigns, PEP can identify if there is missing information for the players that you register in our platform.

To ensure data alignment between your platform and PEP, it's essential to develop a reconciliation process. This process serves as a fail-safe to guarantee that if PEP detects any missing player information, you (the operator) will be notified to sync the missing information using PEP's player CRUD operations. To avoid regulation issues the reconciliation requests are stored in an audit log.

tip

For more details check the Open API Specification here.

• Request Sync Info