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 is not accepted for any reason (that is, the bet is declined), the insurance is NOT used. It is released and becomes available again for another bet.
  • Cash out is not available for an insured bet, so there is no cash-out ↔ insurance interaction to handle.

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

  • 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 successful: the player receives the winning amount, and the insurance is not paid out. No callback is sent — neither bet/insurances/accepted nor bet/insurances/decline. See Insurance statuses and callbacks below.
  • The bet is returned (voided). The bet amount is refunded to the player. A bet/insurances/decline callback is sent only if an accepted refund had already been sent for that insurance before (for example, a lost bet that paid out the insurance and is later voided or recalculated). If no accepted callback was sent, there is nothing to reverse and no decline callback is sent.
Bet insurance Lifecycle diagram

bet_insurance

Insurance statuses and callbacks

bet/insurances/decline is a reversal, not a settlement notification

The bet/insurances/decline callback is sent only to reverse a refund that was previously sent with bet/insurances/accepted. It is never sent for an insurance that was never paid out — in particular, it is not sent when an insured bet wins.

Insurance is consumed at bet placement, not at settlement. Therefore:

Settlement of the insured betCallbackStatus in /insurance/getListInsurance status inside the bet data
Bet lost (insurance paid out) bet/insurances/accepted with the refund_amount used accepted with the paid refund_amount
Bet won None used declined with refund_amount = 0
Bet voided/recalculated after an accepted refund bet/insurances/decline used declined
Bet not accepted (declined at placement) None new (released, available for another bet) —

The /insurance/getList status becomes used when the insurance is applied to an accepted bet and does not change afterwards regardless of how the bet settles. The settlement result is reflected by the insurance status inside the bet data, which is the field to rely on.

Expected from the integrating party on a win

Nothing. No funds are reserved or deducted for the insurance, and there is no need to finalize or decline the insurance yourselves. Simply rely on the insurance status in the bet data.

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 sends a request to the integrating party to cancel the accrued sum of the insurance (the bet/insurances/decline callback).
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.

max_amount is required for the percent rule

For the percent refund rule both percent and max_amount are mandatory. A percent rule sent without max_amount is rejected with 400 request_payload_validation_failed (at_least_one_of on refund_rules.amount). Always include max_amount for type = percent.

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), and it is required for that 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: {   "session_id": "some_session_id",   "any_extra_value": "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: {   "session_id": "some_session_id",   "any_extra_value": "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"
}'

Callback API

CRUD API