◾Bonus API integration

Smartico.ai can issue bonuses using different internal mechanics.

These bonuses are managed on external platforms, such as a casino or sportsbook, with Smartico making calls to a Bonus API to issue the bonuses to players.

Smartico allows for the segmentation of bonuses, ensuring that only specific groups of players can access them. The segmentation is available in all the places where the Bonuses can be issued - Automation rules, Campaigns, Mini-games, Store, Tournaments, Missions, Dynamic Bonuses

The Bonuses after the acquisition are available in the gamification widget UI, where players can see the history and in case bonus is not automatically redeemable, to redeem them.

Smartico can work with any type of the bonuses. It could be

template-based bonuses. When Smartico is calling API by specifying user ID and template ID
cash amount based. When Smartico is passing user ID and amount. Could be real/bonus money
free-spins or free-bets based.
mixed solutions. When part of bonus is defined by template and additional information is enriched dynamically.

Note: the Dynamic Bonuses functionality provides possibility to calculated the amount of bonus based on the custom formula, e.g. "5% of total loss on Poker games during weekend".

To support this feature the Bonus API should provide possibility to pass dynamic amount in the API call.

API concept and implementation

Most of the systems have internal bonus engines that can be exposed through the API to Smartico.

The general logic of such API should look like "Give bonus X to the user Y", where the bonus X is identified by some unique name or ID, and all details of the bonus are managed on the side of the integrated system.

For example for the Casino product, the bonus can be identified as "10FREE_SPIN_IN_GOLDEN_SLOT".

Information about the number of spins and eligible games is managed on the Casino system side, and the Smartico system will only instruct the casino through the API to give 10FREE_SPIN_IN_GOLD_SLOT to the user John1984.

From a technical perspective, the Smartico system supports APIs that are exposed as REST over HTTP/S and can use either GET or POST, with optional "Basic Authorization" or/and security tokens provided in the HTTP headers.

Example of possible call that can be done from Smartico side:

GET /issue-bonus.aspx HTTP/1.1
Host: my-casino.com
Content-Type: application/json
Content-Length: 75

{
    "user_id": "John1984",
    "bonus_template_id": "10FREE_SPIN_IN_GOLDEN_SLOT",
    "smartico_bonus_id":3543567
}

The integrated platform should return an error code and message in the response so that Smartico will track the bonus issuing process properly. For example

{
    "errCode": 105,
    "errMessage": "User has active withdrawal request, the bonus cannot be issued"
}

smartico_bonus_id - it's unique bonus ID on Smartico side. Integrated platform should keep this ID and in case Smartico will send the same smartico_bonus_id again, platform should just respond with OK/Positive response without actually giving bonus on the platform side, Smartico can retry sending same bonus many time if for some reason we do not get response from platform/timeout or other network problem occurred.

For the Dynamic bonuses, Smartico is expecting an API to give variable amount of bonus, e.g.

GET /issue-bonus-dynamic-cash.aspx HTTP/1.1
Host: my-casino.com
Content-Type: application/json
Content-Length: 75

{
    "user_id": "John1984",
    "bonus_cash_amount": 10.55,
    "smartico_bonus_id":3543567
}

Similar to the cash, the Dynamic Bonuses can be used to give variable amount of Free bets or Free pins or any other "countable" entities in the integrated system, e.g.

GET /issue-bonus-dynamic-spins.aspx HTTP/1.1
Host: my-casino.com
Content-Type: application/json
Content-Length: 75

{
    "user_id": "John1984",
    "free_spins_count": 5,
    "smartico_bonus_id":3543567
}

Such calls can be also extended with additional parameters that are specfic for integrated platform, such as:

currency in which to give bonus cash
game_id(s) for which free spins are eligible
expiration_time for the spin/free bets bonuses
etc.

Managing Bonuses from the Smartico Back Office

Every bonus should be registered in the Smartico Back Office under the Gamification \ Bonus templates section.

As soon as the bonus is registered, it can be issued from:

Realtime Journey and Scheduled campaigns. E.g. every time the user makes a deposit above 100 EUR, give him a bonus
Missions & Tournaments
As a prize in mini-games like Spin The Wheel, Scratch Card or MatchX
In exchange for the gamification points in the Store, e.g. you can "sell" 10FREE_SPIN_IN_GOLDEN_SLOT bonus for 100 Points

It's possible to populate a list of bonus codes from the external system. This will simplify the work of the Operator who is going to register bonuses in the Smartico system. In order to have this option, the external system should provide REST HTTP/S API available with GET/POST methods and return a JSON array with the id/name of all bonuses. Example of response

[
    {
        "id": "10FREE_SPIN_IN_GOLDEN_SLOT",
        "name": "10 Free spins on Golden Slot"
    },
    {
        "id": "100PERC_ON_NEXT_DEP500LIMIT",
        "name": "100% on next deposit, maximum 500 EUR"
    },
    ...
]

Note that API should be publicly available, but can be protected with static keys for Basic Authorization of static secret tokens in HTTP headers.

Last updated 2 months ago