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. Login in to your Admin Dashboard Instance and navigate to System Settings and find the menu called Authentication 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

That's it know the Gamanza Engage Platform can send request 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

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 succeed
2. The max retry is reached the platform perform up to 5 retry operations

We always send the entire request back, and we expect you process the bonus in 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 some documentation about HTTP Status codes and its meaning: HTTP response status codes

Bonus List

The operators need to provide a Bonus List and filter API, to make the Casino Operators and Marketing agents the usage of the platform the most seamless as possible. If you enable this API your operators can see the bonus in our platform as a nice dropdowns, reducing the human error factor when a new reward is configured in PEP.

If you don't implement the Bonus List API your Casino Operators should use a input text 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 allow pass multiple values in case your integration requires additional information, and those filters allows the PEP Admin UI to properly display the filters base on your integration requirements.

For customers that have a standard/simple bonus engine where only the name is required the API request 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 we use 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 though 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

It is important to mention that filters enhance the capability of the Admin UI to make easy the work of your marketing team, base on this at least the name filter should be implemented and base on your integration requirements you are the responsible to add the extra filters as required by your integration.

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 needs 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 depends 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 identity token, we need you 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