Bonuses

Bonuses Endpoints

This section will display all available endpoints to get bonus data.

Most of calls requires an authentication token, which will be different from the player’s authentication token. Call to Get authentication token:

Request (POST)

/gateway/bonus/:version/login/:brand_id

Parameters:

{
  "signed_key": "string"
}
Name In Type Required Description
version path string true The API version to use.
brand_id path int true The ID of the casino.
Authorization header string true subject for validation (i.e Banana).
signed_key body string true key for validation (i.e Banana).

Example responses

will return string “Success” in the body and the Authentication in the header “x-auth-token” of the response

{
  "msg": "Success"
}

the header from result should be sent in the header of the next request as “x-auth-token”, with ‘Bearer ’ prefix

Subsections of Bonuses

Bonus Validation

This method validates the parameters of a bonus. use gateway.[msdomain]
This document contains documentation for API version 1 and 2

Request (GET)

/gateway/bonus/{version}/validate/{brand_id}/{coupon}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path string true The ID of the casino. If a brand_id is not provided, all message formats will be fetched from default storage.
coupon path string true Bonus code.
btag query string false Player affiliation reference.
currency query string false Player currency.

Response

Status 200

{
  "frb_at_registration": [
    {
      "language": "de",
      "text": "7 Freispiele für Groove_PlayNGo",
      "wagering": "null3"
    }
  ],
  "bonus_at_registration": 100,
  "frb_at_verification": [
    {
      "language": "de",
      "text": "7 Freispiele für Groove_PlayNGo",
      "wagering": "null3"
    }
  ],
  "bonus_at_verification": 30
}

Status 400

{
  "errMsg": "invalid input - invalid brand id"
}

Status 400

{
  "status": "error",
  "data": "coupon time exceeded"
}

Status 500

{
  "result": "internal server error"
}

Response Parameters:

Name Description
frb_at_registration Array which will contain all available languages for FRB bonus which will be given upon registration, need to choose the relevant language for player (frb_at_registration.language) and show its text.
frb_at_verification Array which will contain all available languages for FRB bonus which will be given upon email verification, need to choose the relevant language for player (frb_at_verification.language) and show its text.
bonus_at_registration Amount which will be awarded to player once he completes the registration, please not that if currency is not sent, amount will be displayed in brand default currency.
bonus_at_verification Amount which will be awarded to player once he verifies his email, please not that if currency is not sent, amount will be displayed in brand default currency.

API VERSION 2

Request (GET)

/gateway/bonus/{version - should be >= 2}/validate/{brand_id}/{coupon}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path string true The ID of the casino. If a brand_id is not provided, all message formats will be fetched from default storage.
coupon path string true Bonus code.
btag query string false Player affiliation reference.
currency query string false Player currency.

Response

Status 200

{
  "registration": {
    "bonus_amount": 1000,
    "wagering_multiplier": 10,
    "frb": [
      {
        "round_count": 25,
        "game_provider": "Betsoft",
        "supported_games": [
          "Primal Wilderness"
        ],
        "wagering_multiplier": 1
      }
    ]
  },
  "verification": {
    "bonus_amount": 10000,
    "wagering_multiplier": 50,
    "frb": [
      {
        "round_count": 10,
        "game_provider": "Pragmatic Play",
        "supported_games": [
          "Floating Dragon Megaways",
          "John Hunter and the Book of Tut Respin™"
        ],
        "wagering_multiplier": 1
      },
      {
        "round_count": 3,
        "game_provider": "Evoplay",
        "supported_games": [
          "Fruit Super Nova 100"
        ],
        "wagering_multiplier": 3
      },
      {
        "round_count": 44,
        "game_provider": "Betsoft",
        "supported_games": [
          "7 Fortune Frenzy",
          "At The Movies",
          "Book of Helios",
          "Dragon Kings NJP"
        ],
        "wagering_multiplier": 3
      }
    ]
  }
}

Status 200, No frb

{
  "registration": {
    "bonus_amount": 1000,
    "wagering_multiplier": 10 
  },
  "verification": {
    "bonus_amount": 10000,
    "wagering_multiplier": 50 
  }
}

Status 400

{
  "status": "Error",
  "data": "",
  "message": "coupon not found",
  "userFriendlyMessage": "coupon not found"
}

Status 500

{
  "error": "internal server error",
  "requestID": "91d3236d-82fe-4c4d-b01c-ea07ffe15af7"
}

Grant Bonus

This method validates the parameters of a bonus. use gateway.[msdomain] Request Parametercomment & givenBy parameters are mandatory for all actionsAdditional Request Parameters Required for each bonus ( request must contain all )

Request (POST)

/gateway/bonus/{version}/grant/{brand_id}/{player_id}/{bonus_action}

Parameters:

{
  "bonusName": "string",
  "newBonusId": "string",
  "amount": 14.3,
  "wageringMultiplier": 3.3,
  "WageringBase": "string",
  "givenBy": "string",
  "comment": "string",
  "wageringRequirement": 0
}
Name In Type Required Description
version path string true The API version to use.
brand_id path int true none
player_id path int true none
bonus_action path string true none
Authentication header string true header received from ‘Login’

Response

Status 200

{
  "refId": 512
}

Status 400

{
  "errMsg": "invalid input - invalid brand id"
}

Status 500

{
  "result": "internal server error"
}

Bonus Type Metadata

Request (GET)

/gateway/bonus/{version}/bonusType/{brand_id}/metadata

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true none
Authentication header string true header received from ‘Login’

Response

Status 200

{
  "metadata": [
    {
      "id": "123",
      "bonusName": "string",
      "line": 0,
      "amountPercent": 0,
      "wageringMultiple": 0,
      "calculateWagering": "string",
      "maximumBalance": 0,
      "maximumAmount": 0,
      "displayType": "string",
      "type": "string",
      "comment": "string",
      "lastEditedBy": "string",
      "isActive": 0,
      "isUsed": 0,
      "isVisible": 0
    }
  ]
}

Status 400

{
  "errMsg": "invalid input - invalid brand id"
}

Status 500

{
  "result": "internal server error"
}

Grant FRB Bonus

Request (POST)

/gateway/bonus/{version}/grant/frb/{brand_id}/{player_id}

Parameters:

{
  "player_id": 1234545,
  "template_id": "20c51ae125482b3768653b50c_1639016587471",
  "bonus_id": "manual__20c51ae125482b3768653b50c_1639016587471",
  "comment": "given because of...",
  "operator": "player"
}
Name In Type Required Description
version path string true The API version to use.
brand_id path int true none
player_id path int true none
Authentication header string true header received from ‘Login’

Response

Status 200

{
  "refId": 512
}

Status 400

{
  "errMsg": "invalid input - invalid brand id"
}

Status 500

{
  "result": "internal server error"
}

Bonus Type Metadata

Request (GET)

/gateway/bonus/{version}/get/frb/{brand_id}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true none
Authentication header string true header received from ‘Login’

Response

Status 200

{
  "frb_templates": [
    {
      "_id": "31eead653fb64ce3b2aa5cef4c384be9",
      "id": "",
      "brand_id": 0,
      "bonusName": "555555plo",
      "bonusDescription": "55555555",
      "active": true,
      "manualBonus": true,
      "providers": [
        {
          "providerId": "Groove_Pragma",
          "number_of_rounds": "1",
          "wagering_multiplier": "1",
          "available_from_date": "",
          "expiration_date": "",
          "message_first_line": "",
          "message_second_line": "",
          "offer_name": "",
          "all_games_used": false,
          "games": [
            {
              "brand_id": 0,
              "provider_id": "",
              "Game_Name": "Hot to Burn",
              "Game_Type": "",
              "CasinoId": 158000070,
              "supported_provider_games": ""
            },
            {
              "brand_id": 0,
              "provider_id": "",
              "Game_Name": "Leprechaun Carol",
              "Game_Type": "",
              "CasinoId": 158000080,
              "supported_provider_games": ""
            }
          ],
          "template_id": "",
          "inner_template_id": ""
        }
      ],
      "changed_by": "",
      "offerValue": "N/A",
      "totalNumberOfRounds": 16,
      "availableFromDate": "",
      "frb_bonus_desc": [
        {
          "language": "en",
          "text": "1 Free spins on Pragmatic Play"
        }
      ],
      "templateInUse": false
    }
  ]
}

Status 400

{
  "errMsg": "invalid input - invalid brand id"
}

Status 500

{
  "result": "internal server error"
}

Grant Bonus By Code

Request (POST)

/gateway/bonus/{version}/grant_bonus_by_code/{brand_id}

Parameters:

{
  "bonus_code": "string"
}
Name In Type Required Description
version path string true The API version to use.
brand_id path int true none
x-auth-token header string true Player session.

Response

Status 200

{
  "status": "Success",
  "data": {
    "refId": 151884,
    "msg": ""
  }
}

Status 400

{
  "errMsg": "invalid input - invalid brand id"
}

Status 500

{
  "result": "internal server error"
}

Wagering Complete Info

Request (GET)

/gateway/bonus/{version}/wagering-complete/{brand_id}/{player_id}/{unique_ref_id}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true none
player_id path int true player unique identifier
unique_ref_id path int true player unique reference for wagering completed event
x-auth-token header string true Player session token

Response

Status 200

{
  "status": "Success",
  "data": [
    {
      "bonus_id": "776262",
      "bonus_money_before": "100",
      "bonus_money_removed": "100",
      "real_money_added": "100",
      "max_win": "unlimited"
    },
    {
      "bonus_id": "776266",
      "bonus_money_before": "11",
      "bonus_money_removed": "11",
      "real_money_added": "11",
      "max_win": "unlimited"
    },
    {
      "bonus_id": "776257",
      "bonus_money_before": "10",
      "bonus_money_removed": "10",
      "real_money_added": "10",
      "max_win": "unlimited"
    }
  ]
}

Status 400

{
  "errMsg": "invalid input - invalid brand id"
}

Status 412 (in case of non-existing details for request details)

{
  "status": "Error",
  "data": "wagering complete in progress",
  "message": "wagering complete in progress",
  "userFriendlyMessage": "wagering complete in progress"
}

Status 500

{
  "result": "internal server error"
}

Response Parameters:

Name Description
bonus_id unique identifier for specific bonus
bonus_money_before bonus money before event in specific bonus
bonus_money_removed bonus money removed from bonus
real_money_added real money added to player balance
max_win max winning definition for bonus, please note that if real_money_added is less than max_win, it might change

Cashback Eligibility

Request check (GET)

/gateway/financials/{version}/check/cashback/eligibility/{brand_id}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true none
X-Auth-Token header string true header received from ‘Login’

Response

Status 200

{
  "status": "Success",
  "data": {
    "eligible_deposit": 580,
    "base_cashback_amount": 29,
    "cashback_amount": 72.5,
    "vip_level": "Platinum",
    "minimum_cashback_amount": 20,
    "maximum_balance": 1,
    "decline_reasons": [
      "Cashback amount is less than minimum required",
      "Player balance is high"
    ],
    "bonus_template_name": "abc",
    "eligible": false
  }
}
{
  "status": "Success",
  "data": {
    "eligible_deposit": 580,
    "base_cashback_amount": 29,
    "cashback_amount": 72.5,
    "vip_level": "Platinum",
    "minimum_cashback_amount": 20,
    "maximum_balance": 1,
    "decline_reasons": [],
    "bonus_template_name": "abc",
    "eligible": true
  }
}

Decline Reasons

  • Cashback amount is less than minimum required
  • Player balance is high
  • Player has pending withdrawal
  • Player has open round

Status 400

{
  "status": "Error",
  "data": null,
  "message": "invalid input - invalid brand id",
  "userFriendlyMessage": "invalid input - invalid brand id"
}

Status 500

{
  "status": "Error",
  "data": null,
  "message": "internal server error",
  "userFriendlyMessage": "internal server error"
}

Request Claim (POST)

/gateway/bonus/{version}/cashback/eligibility/{brand_id}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true none
X-Auth-Token header string true header received from ‘Login’

Response

Status 200

{
  "status": "Success",
  "data": {
     "refId": 1825996,
      "msg": ""
  }
}

Status 400

{
  "status": "Error",
  "data": null,
  "message": "player is not eligible for cashback",
  "userFriendlyMessage": "player is not eligible for cashback"
}

Status 500

{
  "status": "Error",
  "data": null,
  "message": "internal server error",
  "userFriendlyMessage": "internal server error"
}

Deposit Bonus Eligibility

Request (GET)

/gateway/bonus/{version}/{brand_id}/deposit_bonus/eligibility

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true none
X-Auth-Token header string true header received from ‘Login’
bonus_code query string true The bonus code the players want to use
payment_method query string true the payment method the player wants to use
amount query decimal true the amount the players wants to deposit

Response

Status 200

{
  "status": "Success",
  "data": {
    "bonus_available": true
  }
}
{
  "status": "Success",
  "data": {
    "bonus_available": false,
    "decline_reasons": [
      [{"reason": "Bonus Inactive", "data": ""}, {"reason": "Limit Period", "data": "5"}],
      [{"reason": "Previous Bonus Required", "data": "Reqbon"}]
    ]
  }
}

Decline Reasons

  • invalid_bonus_code
  • bonus_opt_out
  • pending_withdrawals
  • bonus_inactive
  • date_restriction
  • currency_restriction
  • deposit_amount
  • limit_period
  • approved_withdrawal_amount
  • btag_restriction
  • country_restriction
  • day_restriction
  • unfinished_rounds
  • language_restriction
  • marketing_segment
  • deposit_count
  • payment_method
  • affiliate_id
  • player_balance
  • player_real_balance
  • previous_bonus_required
  • previous_bonus_restriction
  • vip_level
  • vip_segmentation

Status 400

{
  "status": "Error",
  "data": null,
  "message": "invalid input - invalid brand id",
  "userFriendlyMessage": "invalid input - invalid brand id"
}

Status 401

{
  "errMsg": "invalid input - invalid token"
}

Status 500

{
  "status": "Error",
  "data": null,
  "message": "internal server error",
  "userFriendlyMessage": "internal server error"
}

Forfeit Bonuses

Request (POST)

/gateway/bonus/{version}/manual_bonus/forfeit_bonuses/{brand_id}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true none
X-Auth-Token header string true header received from ‘Login’

Response

Status 200

{
  "status": "Success",
  "data": {
    "bonus_amount_deducted": "10.4",
    "wagering_amount_deducted": "100"
  }
}

Status 207

{
  "status": "Failure",
  "data": {
    "bonus_amount_deducted": "10.4",
    "wagering_amount_deducted": "100"
  },
  "message": "Some bonuses were forfeited, but some were not",
  "userFriendlyMessage": "Some bonuses were forfeited, but some were not"
  
}

Status 400

{
  "status": "Error",
  "data": " Player has open rounds.",
  "message": "Player has open rounds.",
  "userFriendlyMessage": "Player has open rounds."
}
{
  "status": "Error",
  "data": " Player doesn't have an active bonus.",
  "message": "Player doesn't have an active bonus.",
  "userFriendlyMessage": "Player doesn't have an active bonus."
}

Status 401

{
  "errMsg": "invalid input - invalid token"
}

Status 500

{
  "status": "Error",
  "data": null,
  "message": "internal server error",
  "userFriendlyMessage": "internal server error"
}

Get Recent Active FRB Bonuses Statuses

Request (GET)

/gateway/bonus/{version}/data/{brand_id}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true none
X-Auth-Token header string true Player Login Session

Response

Status 200

{
  "status": "Success",
  "data": [
    {
      "frb_template_name": "3 diff provider 1 g multi games",
      "frb_provider": "Pragmatic Play",
      "total_rounds": "23",
      "frb_game_name": "Sweet Bonanza",
      "frb_game_id": "158000003",
      "frb_bonus_description": "dfbdfbdfb",
      "event_time": "2025-04-10 10:02:06"
    }
  ]
}

Status 400

{
  "status": "Error",
  "data": {
    "errMsg": "invalid input - invalid brandId"
  },
  "message": "invalid brand_id",
  "userFriendlyMessage": "invalid brand id"
}

Status 401

{
  "status": "Error",
  "data": {
    "errMsg": "invalid input - invalid token"
  },
  "message": "authentication failed",
  "userFriendlyMessage": "Authentication failed"
}

Status 500

{
  "result": "internal server error"
}

Good Will Gesture bonus

Request Get GWG Parameters (GET)

/gateway/financials/{version}/gwg/eligibility/{brand_id}/{player_id}

Parameters:

Name In Type Required Description
version path string true The API version to use.
brand_id path int true none
player_id path int true none
Authorization header string true form prop AI_CHAT_AUTH_HEADER

Response

Status 200

{
  "status": "Success",
  "data": {
    "total_balance": 10,
    "bonus_opt_out": false,
    "logged_in": true,
    "vip_level": 1,
    "total_withdrawal_amount": 0,
    "total_deposit_amount": 0,
    "total_bonus_received": 10,
    "withdrawal_ratio": 0,
    "bonus_ratio": 0,
    "pending_kyc_verification": false,
    "cash_gift_eligible_deposits": 0,
    "cash_gift_eligible_deposits_eur": 0,
    "country": "NZ",
    "pending_withdrawal": 0
  }
}

Status 400

{
  "status": "Error",
  "data": null,
  "message": "invalid input - invalid brand id",
  "userFriendlyMessage": "invalid input - invalid brand id"
}

Status 500

{
  "status": "Error",
  "data": null,
  "message": "internal server error",
  "userFriendlyMessage": "internal server error"
}

Request Grant Manual Bonus (POST)

/gateway/bonus/{version}/gwg/{brand_id}/{player_id}

Parameters:

{
  "bonus_name": "string",
  "bonus_amount": 100
}
Name In Type Required Description
version path string true The API version to use.
brand_id path int true none
player_id path int true none
Authorization header string true form prop AI_CHAT_AUTH_HEADER

Response

Status 200

{
  "status": "Success",
  "data": {
     "refId": 1825996,
      "msg": ""
  }
}

Status 400

{
  "status": "Error",
  "data": null,
  "message": "player is not eligible for cashback",
  "userFriendlyMessage": "player is not eligible for cashback"
}

Status 500

{
  "status": "Error",
  "data": null,
  "message": "internal server error",
  "userFriendlyMessage": "internal server error"
}