> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/technical-guides/bonus-api-integration.md). # 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](/welcome/products/crm-automation/automation-rules.md), [Campaigns](/welcome/products/crm-automation.md), [Mini-games](/welcome/products/mini-games.md), [Store](/welcome/products/gamification-basics/marketplace.md), [Tournaments](/welcome/products/gamification-basics/tournaments.md), [Missions](/welcome/products/gamification-basics/missions.md), [Dynamic Bonuses](/welcome/products/general-concepts/dynamic-rewards.md) 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. Bonuses follow two distinct fulfillment flows: * **Automatic Issuance:** Smartico immediately triggers the external Bonus API upon event completion. Once the partner API returns success, the bonus transitions to **Redeemed**. * **Claimable (Manual) Redemption:** The bonus is granted to the player as a claimable voucher in the Gamification Widget with status **Coupon Issued**. The call to the external Bonus API is executed only when the player explicitly clicks "Claim". * **Status Lifecycle:** Smartico tracks bonus states throughout their lifecycle: **New** (queued for dispatch), **Coupon Issued** (awaiting player redemption), **Redeemed** (successfully delivered and confirmed by partner API), **Redeem Failed** (rejected by API or timed out), and **Expired**. 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. {% hint style="info" %} Note: the [Dynamic Bonuses](/welcome/products/general-concepts/dynamic-rewards.md) functionality provides the ability to calculate the bonus amount based on a custom formula, e.g., "5% of total loss on Poker games during the weekend". To support this feature the Bonus API should provide possibility to pass dynamic amount in the API call. Each dynamic bonus type supports **one dynamic parameter** (such as dynamic cash amount or dynamic free spins count). If an operator needs to issue two variable parameters simultaneously (for example, free spins and cash), two separate bonus templates should be configured. {% endhint %} ## 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: 
POST /issue-bonus.aspx HTTP/1.1
Host: my-casino.com
Content-Type: application/json
Content-Length: 75

{
    "user_ext_id": 123,
    "bonus_template_id": 55, // e.g. "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 ```json { "errCode": 105, "errMessage": "User has active withdrawal request, the bonus cannot be issued" } ``` **smartico\_bonus\_id** is the unique bonus issuance identifier generated by Smartico. The integrated platform must store this identifier to ensure idempotency. If Smartico resends a request with the same smartico\_bonus\_id (for example, following a network timeout), the platform must return an OK/success response without granting duplicate bonuses. Smartico automatically retries unacknowledged requests every 10 minutes during a retry period set by Smartico. If the platform returns an explicit error response, the bonus is not retried, unless the **Retry bonuses rejected by the platform** setting in **Label settings** is ON; ask your Success manager to change it. For the [Dynamic bonuses](/welcome/products/general-concepts/dynamic-rewards.md), Smartico is expecting an API to give variable amount of bonus, e.g. 
POST /issue-bonus-dynamic-cash.aspx HTTP/1.1
Host: my-casino.com
Content-Type: application/json
Content-Length: 75

{
    "user_ext_id": 123,
    "bonus_cash_amount": 10.55,
    "smartico_bonus_id":3543567
}
Similar to cash, [Dynamic Bonuses](/welcome/products/general-concepts/dynamic-rewards.md) can be used to give a variable amount of Free Bets, Free Spins, or any other countable entity in the integrated system, e.g. 
POST /issue-bonus-dynamic-spins.aspx HTTP/1.1
Host: my-casino.com
Content-Type: application/json
Content-Length: 75

{
    "user_ext_id": 123,
    "free_spins_count": 5,
    "smartico_bonus_id":3543567
}
Mixed approach, when the bonus engine is based on a template, but with the ability to redefine the free spins count or cash amount: ```http POST /issue-bonus.aspx HTTP/1.1 Host: my-casino.com Content-Type: application/json Content-Length: 75 { "user_ext_id": 123, "bonus_template_id": 55, // e.g. "10FREE_SPIN_IN_GOLDEN_SLOT" "free_spins_count": 11, "smartico_bonus_id":3543567 } ``` Such calls can also be extended with additional parameters specific to the 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. ### Sending bonuses in batches If your platform bonus API can accept many bonuses in one call, Smartico can group bonuses and send them in batches instead of one by one. This is turned on with the **Send bonuses to the platform in batches** setting in **Label settings**; ask your Success manager to change it. Batch sending needs extra integration work on the Smartico and platform side. Bonuses bought in the Store and bonuses from mini-games are always sent one by one. ### Outbound Call Logs and Diagnostics Smartico logs the outbound HTTP request (URL, method and body), the response code, and the response body for every bonus issuance attempt. Operators can inspect these records in the Back-Office (they can appear a few minutes after the call): open the player's profile, go to the **Bonuses** tab, and click **Details** on the bonus to open the **API calls history**. This provides complete visibility into partner API rejections (such as eligibility failures or duplicate requests) and network timeouts. ## Managing Bonuses from the Smartico Back Office Every bonus must be registered in the Smartico Back-Office under the Tools > Bonuses > Bonus templates section.

Registering bonus in Smartico Back Office

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 ### Bonus Safety Caps and Limits To prevent accidental over-issuance or promotional abuse, Smartico enforces issuance limits: * **Daily Safety Cap:** Smartico limits the number of bonuses one real (non-test) player can receive per day (UTC) across all sources. The limit is set by the **Max bonuses per player per day** setting in **Label settings**; the value can differ, so check it for your label. * **Ignore Bonus Cap Setting:** For critical transactional rewards or high-value VIP flows, operators can enable the **Ignore bonus CAPs** toggle on specific campaign nodes or automation rules. 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 ```json [ { "id": 55, "name": "10 Free spins on Golden Slot" }, { "id": 56, "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. ### Network and Firewall Configuration Because Smartico dispatches outbound API requests from dedicated server clusters, the operator's firewall or Cloudflare/WAF configuration must whitelist Smartico's outgoing IP addresses. Communication must use standard HTTPS with valid SSL/TLS certificates issued by a recognized certificate authority. Custom self-signed certificates and VPN or SSH tunnels are not supported. ## FAQ **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 scenarios are fully controlled by the CRM team that operates Smartico. There are many mechanics that can trigger the issuing of a bonus, e.g. * User can win a specific bonus in a mini-game. The operator controls the exact 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 fulfill specific requirements of a Campaign or Automation rule and get a bonus as part of a 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 different API endpoints or on a single endpoint with a parameter indicating the bonus type. Smartico is flexible to work in any way defined by your 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 can be passed, depending on your system's wallet architecture. Most current casino and sports platforms are single-wallet based, meaning a specific user has one fixed-currency wallet for real money, so passing currency is redundant. In multi-currency or crypto environments, currency can be explicitly passed in the payload. 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 must determine whether bonus issuing succeeded or failed. The response format can be JSON, XML, or standard HTTP status codes. It is essential to return a machine-readable error code to indicate success or failure, along with a human-readable description of any failure to facilitate operational troubleshooting. **Q: What security options are supported by Smartico when calling an API?** A: Smartico can use HTTP headers to pass security tokens, support JWT signed messages, Basic Authentication, or other custom authorization mechanisms 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 **Q: Why does a bonus display as "Redeemed" in Smartico, but "Active" on our casino platform?** A: In Smartico, **Redeemed** means Smartico successfully transmitted the bonus issuance request to your Bonus API and received a positive confirmation. On the casino or sportsbook platform, the bonus remains **Active** until the player completes the wagering requirements or consumes the free spins. Smartico acts as issuance middleware and does not manage real-time gameplay balances. **Q: How do we troubleshoot bonuses that fail with status "Redeem Failed"?** A: Navigate to the player profile in the Smartico Back-Office and open the **Bonuses** tab. Click **Details** on the failed bonus to open the **API calls history** and review the exact request payload sent by Smartico and the response returned by your API. If your API returned an HTTP 4xx/5xx code or an error object, the message will reveal the business rejection reason (e.g. KYC incomplete or active withdrawal). If the response is empty, it indicates a network timeout. **Q: Can Smartico display remaining free spins or wagering progress for a player?** A: No. Once a bonus is successfully issued to the player's account on your platform, gameplay sessions, spin consumption, and wagering requirements are tracked exclusively by your casino engine and game providers. Smartico records the initial grant confirmation and external transaction ID. **Q: How can we prevent players with an active bonus from receiving another bonus?** A: You can prevent duplicate bonus acquisition using two complementary methods: 1. **Smartico Segmentation:** In your Campaign or Journey rules, add conditions checking whether the player has recently received a specific bonus template or holds an unredeemed voucher. 2. **API-Level Validation:** When Smartico calls your Bonus API, your platform can evaluate player eligibility and return a structured error response (e.g. `errCode: 105`) if the player already holds an active bonus. Smartico will record the rejection and mark the bonus as Redeem Failed without retrying (unless the **Retry bonuses rejected by the platform** setting in **Label settings** is ON). **Q: How does Smartico handle multi-brand bonus templates under one label?** A: When operating multiple brands under a single label, Smartico allows you to configure a **Multi-Brand Bonus Template**. Within a single bonus definition, you can map different external template IDs for each brand. When a player receives a reward from a shared campaign or mini-game (such as Spin the Wheel), Smartico automatically resolves and passes the correct external template ID matching the player's brand. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.smartico.ai/welcome/technical-guides/bonus-api-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.