Bonus
The bonus event will give you the ability to see actual bonus costs associated to your campaigns. It will also allow you to trigger activities on bonus status changes, e.g. if it's lost too quickly.
REST API
RabbitMQ Connector
Kafka Connector
⬆️ POST /v1/integration/bonus
RabbitMQ Message Properties
key | value |
type | BONUS |
The type is expected as a property (but not in the payload) of the RabbitMQ Message. Any header will be ignored.
Kafka Message Headers
key | value |
type | BONUS |
Business Rules:
- Every created bonus needs to have its conclusion [Completed, AutoCompleted, Forfeited, Expired or Lost].
- A user_bonus_id within a status should be unique.
- It's important that only one event is sent when the status of the bonus is changed. Multiple events of the same status will result in the segmentation data being incorrect.
Request
When sending 'free spins' bonuses, we expect the first bonus event to be sent once the free spins rounds have been completed and with the correlating "amount" that was won.
If you wish to send data when the free spins has been issued, you might send this as a 'Custom Event'.
Required properties are marked with *
Key | Type | Description |
amount * | float | The amount assigned to the bonus. |
bonus_code | string | Indication as to the nature of the promotion eg “WELCOME100” |
bonus_id * | string | Unique identifier for each bonus campaign. |
bonus_turned_real | float | Bonus amount turned to real money, if wagering is finished |
currency * | string
Format: ISO4217 | Player currency |
exchange_rate * | float | The exchange rate at the timestamp |
locked_amount | float | Bonus amount locked to wagering |
meta | object | If meta data is required to be sent |
origin * | string | This value can be used to identify the brand or jurisdiction the player is playing on |
product * | string
Accepted Values:
"Casino"
"Sportsbook"
"Lotto"
"Poker"
"Live Casino" | Defines the product associated to the bonus |
required_wagering_amount | float | Required wagering amount of bonus |
status * | string
Accepted Values:
"Created"
"Completed"
"AutoCompleted"
"Forfeited"
"Expired"
"Lost" | The status assigned to the bonus at the moment of the real time event being sent. |
timestamp * | string
Format: RFC3339 | Timestamp of the event being sent. Time accurate to milliseconds is required here to ensure accuracy. |
type * | string
Accepted Values: "NoDeposit"
"WelcomeBonus"
"CashbackBonus"
"ReloadBonus" "WagerFree"
"FreeSpins" "RiskFreeBet" "Undefined" | Has to be one of the specificied values in the list. If not, please send "Undefined". We can assist on mapping your current bonus types to the list defined here. |
user_bonus_id | string | Unique identifier of the bonus credited to a player. Can be set as a random value, suggestion is to be user id + bonus id. |
user_id * | string | User id of the player the bonus has been credited to. |
is_free_money | boolean | Indicates whether or not the transaction is made using a free to play wallet, such as Gold Coins or any other virtual currency.
If the property is not included in the payload it will default to false |
fasttrack_references | object | Data provided by Fast Track on any bonus crediting requests.
Read more about the implementation here. |
Good Practices - Bonus Type
When mapping your bonus type to one of the accepted values by Greco, it can be a challenging task. Keep in mind that Greco operates through several operators, and we work with the most common types in the industry.
Try to avoid sending an "Undefined" bonus type.
Status descriptions
Status | Description |
Created | When the bonus has been claimed and the funds are added to the player’s account. |
Completed | If the wagering requirement is fulfilled and the bonus funds are turned into real funds. |
AutoCompleted | If your system automatically removes the bonus with a general setting.
e.g. Bonuses are autocompleted if the balance reaches under €0.10 |
Forfeited | If the bonus has been forfeited. |
Expired | If the validity period of the bonus has expired. |
Lost | If the player has run out of bonus balance. |
Sequence of Events
The bonus_id and the user_bonus_id together make a unique key. Every Created bonus needs to have its conclusion: Completed, AutoCompleted, Forfeited, Expired or Lost. So if a {bonus_id:1, user_bonus_id:1, status:Created} is sent, at some point a {bonus_id:1, user_bonus_id:1, status:Completed} needs to be sent.
Scenario A - Bonus Created and Completed
Bonus Event - Created
First, we should receive a Bonus Event with its bonus_id and user_bonus_id having its status as Created
{bonus_id:1, user_bonus_id:1, status:Created, ...}
Bonus Event - Completed
Once the bonus is completed, we should then receive a Bonus Event with its bonus_id and user_bonus_id having its status as Completed
{bonus_id:1, user_bonus_id:1, status:Completed, ...}
Scenario A - Bonus Created and Expired
Bonus Event - Created
First, we should receive a Bonus Event with its bonus_id and user_bonus_id having its status as Created
{bonus_id:1, user_bonus_id:1, status:Created, ...}
Bonus Event - Expired
Once the bonus is completed, we should then receive a Bonus Event with its bonus_id and user_bonus_id having its status as Expired
{bonus_id:1, user_bonus_id:1, status:Expired, ...}
The same must be followed for AutoCompleted, Forfeited or Lost status
If the user_bonus_id is sent with the same status, even with a different bonus_id and amounts, it will be considered a duplicate event, and the last one will be discarded, once the user_bonus_id is the user bonus crediting identification.