Skip to content

Bet insurance

General information

Bet-insurance is a betting functionality that allows players to insure their bets and receive payouts if they lose.

Information about all actions with bet insurance is stored in the Betting Platform (for example, available unused and therefore available insurance, all insurances on the player's bet).

Example

When players place bets, they are offered to insure their bets by 10% of the bet amount (the integrating party can set a percentage or a fixed sum insured) → a player bets 100 UAH and chooses to insure their bet. If the bet is lost, 10 UAH will be credited to the player's account.

Bet insurance

The type of insurance (a fixed amount or a percentage of the bet amount) is chosen when a bet is placed in the bet slip.

The amount of the insurance payout/reimbursement percentage is set by the integrating party.

  • A player can place bets with certain parameters set by the integrating party. For example, if you set the parameters: sport - football, bet amount - 10 EUR, then when adding a bet that meets the specified parameters to a bet slip, the player can choose the available insurance.
  • If the player applies insurance to a certain bet, the bet is considered insured after placing the bet. If insurance has already been applied, it is considered used and no longer available.
  • If the bet to which the player wanted to apply the insurance has not been accepted for any reason, the insurance is NOT used and can be applied to another bet.

After the end of a sporting event on which an insured bet has been placed, the following betting settlements are possible:

  • The bet is successful: the player receives the payout the player receives the winning amount. The betting platform will send a bet/insurances/decline callback so that the integrating party marks the insurance as declined.
  • The bet is lost: the player receives the sum insured (a percentage of the bet amount or a fixed amount). The betting platform will send a bet/insurances/accepted callback so that the integrating party has recharged the player's balance.
  • The bet is returned. The bet amount is refunded to the player. The betting platform will send a bet/insurances/decline callback so that the integrating party marks the insurance as declined.
Bet insurance Lifecycle diagram

bet_insurance

Implementation on the Betting Platform

The algorithm for paying out insurance if the bet loses:

  • After the match is over and the bet has lost, the Betting Platform analyzes what amount or percentage of the bet must be paid out to the player.
  • The Betting Platform sends a request to the integrating side to accrue this insurance.
  • The amount or percentage of the bet is paid out to the player. The refunded amount/percentage of the bet will be displayed in the player's account.
  • If the match is over, but the match score was canceled, the Betting Platform a request to the integrating party to cancel the accrued sum of the insurance.
Conditions

Players can be given an opportunity to insure their bets if they meet the conditions set by the integrating party. To create a bet insurance request, the integrating party must send the following conditions in the post/insurance/create and post/insurance/update methods:

TypeConditionDescription
BetDetails type [single, express, system] Type of bet: single, express (combo), or system. Types of bets are described in detail on the page: /betting/bet/.
odds_count Range of odds count in a bet (values max, min).
total_odds_coefficient Range of the total odds coefficient of a bet (values max, min).
system_size Number of elements in a bet of the system type (values max, min).
odds_coefficient Range of the odd coefficient on the outcome of the event (values max, min).
combinations_count Number of combinations in a bet of the system type (values max, min).
sport IDs of the kind of sports.
tournament Tournament IDs.
sport_event IDs of the sport event.
market_types ID of the market type.
competitor IDs of a competitor in a sport event.
stake_amount_range Range of the bet amount (values max, min).
Money currency_code Currency code in the ISO 4217 (alfa-3) format, for example, "USD".
expires_at Expiration date (date and time) in the DATE_RFC3339 format.
foreign_params A field in which you can send and receive any customizable parameters.

Additionally, for bet insurance it is necessary to send the conditions of the insurance payout depending on the selected strategy. There are two insurance strategies:

  • RefundAmountAmountRule – a fixed amount is paid out;
  • RefundAmountPercentRule – a percent of the bet amount is paid out but not more that the values of the max_amount field.

TypeSubtypeConditionDescription
RefundRulesamounttypeType of insurance: a fixed amount or a percent of the bet amount. Value of the field = amount or percent respectively.
amountInsurance amount that is refunded to the player's balance in case of the bet loss (the RefundAmountAmountRule strategy).
percentPercent of the bet amount that is refunded to the player's balance in case of a bet loss (the RefundAmountPercentRule strategy). It can be expressed as a numeric value with up to 12  decimal places.
max_amountThe maximum limit of the insurance payout amount that is refunded to the player's balance in case of a bet loss. max_amount works only if type = percent (the RefundAmountPercentRule strategy). It can be expressed as a numeric value with up to 12  decimal places.
strategiestypeType of insurance: a fixed amount or a percent of the bet amount. Value of the field = amount or percent respectively.
max_odds_count_loseThe maximum number of outcomes of a sport event in which a player can lose but still receive insurance payout. For example, a player loses in 4 outcomes, max_odds_count_lose = 3, the insurance amount will not be paid. If a player loses in 2 outcomes, the insurance payout will be maid.

Callback API

Note

You can find the basic implementation of the callback server written in Node.js in our GitHub repository at databet-cloud/callback-server-example.

Important

Please ensure that all callbacks are processed idempotently. Due to our at-least once guarantee, it's possible for a callback to be delivered to the server more than once. Always use the request_id to distinguish and manage each callback appropriately. If a request is duplicated, it is crucial to respond with the same response code and content as the initial response. Consistency in handling and responding to repeated requests ensures seamless operation.

Bet insurance callbacks SHOULD be implemented on the integration side only if such functionality is required.

cURL examples

Replace the {callback-api-server} with your callback API server URL and run the following commands to test bet insurance callbacks:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
curl -X 'POST' \
http://{callback-api-server}/bet/insurances/accepted \
-H 'accept: */*' \
-H 'Foreign-Params: {   "some_token": "some_token_value",   "internal_player_id": "123" }' \
-H 'Content-Type: application/json' \
-d '{
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "bet_id": "AAAAAAAAAAAAAAAAAaVSZ1rf1k0BuhAAAOAdRQAY",
    "bet_insurance_id": "129965e5-4279-4a85-a454-89f58192799d",
    "refund_amount": "5.5"
}'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
curl -X 'POST' \
http://{callback-api-server}/bet/insurances/decline \
-H 'accept: */*' \
-H 'Foreign-Params: {   "some_token": "some_token_value",   "internal_player_id": "123" }' \
-H 'Content-Type: application/json' \
-d '{
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "bet_id": "AAAAAAAAAAAAAAAAAaVSZ1rf1k0BuhAAAOAdRQAY",
    "bet_insurance_id": "129965e5-4279-4a85-a454-89f58192799d"
}'

Swagger

API

Swagger