Bonus API integration
Last updated
Was this helpful?
Last updated
Was this helpful?
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 - , , , , , ,
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.
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:
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
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.
Mixed approach, when the Bonus engine is based on template, but with possibility to redefined free spins count / cach amount
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.
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
Note that API should be publicly available, but can be protected with static keys for Basic Authorization of static secret tokens in HTTP headers.
Q: How Smartico can get list of bonuses from the platform
A: The list of bonus templates can be retrieved by Smartico from your API or from Database.
In both options we are flexible:
we can pass additional parameters in the API call,
the security mechanism for API can be also define according to your vision
you can request specific period to reload bonuses, for example every 5 minutes
the output format can be JSON, XML and or any other standard of structured data
Q: How will Smartico system determine which bonus to assign in a particular scenario
A: The scenarious are fully controlled by CRM team that is going to operate Smartico. There are many mechanics that can trigger giving of the bonus, e.g.
User can win speciifc bonus in mini-game. The operator is controlling which exactly bonus and probability of winning
User can complete a mission, win tournament, sport prediction or quiz and get as a reward a bonus
User can "buy" specific bonus from the Store, but paying with gamification points
User can full-fill specific requirements of Campaign or Automation rule and get a bonus as part of marketing initiative.
Q: what is the difference between /issue-bonus.aspx and /issue-bonus-dynamic-cash.aspx?
A: All examples here are given just as an examples. In most of the platform that we are facing there are 3 main types of bonuses that makes sense to integrate (but could be more)
Free spins
Cash money that are going to bonus balance with speciifc wagering requirements
Free bets for sport
Depending on API design, these bonuses are exposed on differet APO end-points or could be on one end-point but to have some parameter that is indicating what is the type of bonus.
Smarico is flexible to work in any of the way defined by API.
Q. Is it possible to add other parameters, such as currency and amount or some other values?
A: The general answer - yes, its possible.
The amount parameter is very common for all types of bonuses, e.g. 'Give 5 free spins', the amount here is 5, 'Give 10 EUR cash', the amount here is 10. Its good to have flexibility to pass amounts in bonus API as it gives more flexibility from operational perspective.
The currency parameter is possible to pass, but the question is about semnatic behind this parameter. As most of the current casino/sport systems right now are "single-wallet" based, which means that speciifc user has only one wallet for real money and the currency is fixed. From this perspective there is no much point to pass currency in the API call, because platform knows it anyway.
The currency could make sense in the multi-wallet platforms, for example user has 2 wallets - one is EUR and another one BTC. In such case Smartico can pass currency as parameter to indicate to which wallet to give the bonus, but this topic need to be discussed in details for specific needs.
Q. What should be response from API?
A: In general, Smartico should understand if bonus issuing succed or failed. The format of response doesn't mater, it can be JSON/XML or any other, what is important is to have 2 fields that are indicating error code on which we can understand its succed or not and human readable description of the error, which will make it easier to investigate reasons of failer in future.
Q: What are security options can be supported by Smartic when calling API
A: We are flexible to use use HTTP-headers to pass security token, can work with JWT signed mesages or any other mechanics that are defined by your API.
We do not support custom signed SSL certificates and we are not building VPN/SSH tunnels
Q: We have multiple brands, can we have different list of bonus templates and different API end points?
A: Yes, bonus lists can be split, same goes for API end points and any credentials. Its important to note that when mutilple-brands operated under one label, you may take 2 different approaches in terms of bonuses, lets review it on the example of "Spin the wheel"
In first approach, you can create a "spin the wheel" game targeting all users of all your brands, and lets assume there is a prize "10 EUR cash" on some sector of the wheel. Because this prize can be won by users of any brands, the right approach will be to define "Multi-brand bonus". When on Smartico side the bonus defined as one entity, but inside it is pointing to different bonus templates for different brands.
In second approach, you can decide that you will create separate "Spin the wheel" games for different users of different brands. In such case even though each wheel may have "10 euro cash" bonuses, each of them will be linked to the different bonus templates.
Both approaches are valid and supported by Smartico, decision to use them is fully depends on your CRM team strategy about building campaigns, segments and gamification activities
For the , Smartico is expecting an API to give variable amount of bonus, e.g.
Similar to the cash, the can be used to give variable amount of Free bets or Free pins or any other "countable" entities in the integrated system, e.g.
