Glossary

API

The set of HTTP methods through which a partner authenticates, creates coupons, and retrieves their states.

Active Coupon

A coupon that is still awaiting a settlement result. Retrieve it through:

GET /api/partner/coupons/active

Asian Market

A market whose result may include a half win or half loss. In the coupon model, such a market is marked by asian.

Bearer JWT

A signed client account token obtained through /api/partner/login.

Sent as:

Authorization: Bearer <token>

The JWT determines coupon ownership. An administrative token cannot be used with client methods.

Callback

An HTTP POST sent by the SportAPI Coupon Settlement System to the partner URL when the settlement state changes.

Callbacks are optional. A partner may retrieve results only through the API or use both methods.

Callback Secret

A secret phrase created by the manager when callbacks are enabled. It is used as the HMAC-SHA256 key and stored only on the partner server.

Cashout

An estimated value of an active coupon before its normal completion.

The current function is under development, is not fully tested, and is not intended for production. The available experimental method does not sell a coupon or change any balance.

`batchId`

Identifier of a specific callback batch version.

a repeated delivery of the same batch has the same batchId;
a new settlement state receives a new batchId;
it is not a coupon ID or bet ID.

Used for delivery deduplication.

Client Account Balance

The partner balance within the SportAPI Coupon Settlement System.

Upon successful creation, the API automatically deducts the amount of all created coupons from it. It is not the end-user balance in the partner system.

`body`

The common API envelope field containing the operation result or additional error data.

Its type depends on the endpoint: object, array, string, or null.

`calculate_coef`

The final settlement multiplier of the entire coupon. In the complete model, it is null before final settlement.

Named calculate_coefficient in callbacks.

`calc_coef`

The settlement multiplier of an individual bet:

win — original odds;
loss — 0;
return or push — 1;
half loss — 0.5;
half win — (coef + 1) / 2.

The bet field is named calculate_coefficient in callbacks.

`calculate_date`

Coupon or bet settlement time in Unix milliseconds.

It is null before settlement. The value 0 is not used for an unsettled object.

`code`

Overall business operation result:

1 — success;
0 — error.

HTTP 200 with code = 0 is not a successful business operation.

`coupon_code`

The public coupon code, usually consisting of 12 digits:

000000000272

Store it as a string with leading zeros. It is the primary link to the partner system.

`coupon_type`

Coupon type:

1 — single;
2 — accumulator.

`error_code`

Numeric machine-readable reason for a business error. Use it in program logic instead of comparing error_message text.

HMAC-SHA256

Callback signature algorithm. The signature is calculated over the exact raw JSON bytes using callback_secret.

Sent as:

X-Coupon-Signature: sha256=<hex>

HTTP Endpoint

A URL accepting a specific HTTP method. SportAPI provides the client endpoints; the partner creates the callback endpoint.

Idempotency

A processing property under which repeating an event does not repeat its business effect.

For example, a repeated callback with the same batchId must not create a second credit.

Financial idempotency additionally protects against the same result received through different sources: callback and polling.

Inbox

The partner’s internal reliable queue for storing incoming callbacks before further business processing.

JWT

See Bearer JWT.

`lang`

A two-letter language code for names in the coupon.

About 50 languages are supported. The language is fixed at creation; an existing coupon cannot currently be retrieved in another translation.

`line`

Prematch feed: outcomes for events before they begin.

In the pointer and model:

line_type = line
is_live = false

`live`

The feed for an event already in progress.

In the pointer and model:

line_type = live
is_live = true

`mode`

Rule for handling changed odds:

reject — reject them;
accept — accept them according to mode_type.

`mode_type`

Direction of odds change that may be accepted with mode = accept:

1 — increase only;
2 — decrease only;
3 — any change.

`multi`

Rule for creating coupons from list_bets:

false — one combined single or accumulator;
true — a separate single for every entry.

With multi = true, amount applies separately to every coupon created.

Outbox

The reliable internal queue of outgoing callbacks in the SportAPI Coupon Settlement System.

Partner

A company or system that accepts bets from end users and connects to the SportAPI API.

The partner independently manages its users, their balances, bet slips, and financial transactions.

Polling

Periodic requests for coupon states through the Client API.

It may be used:

without callbacks;
as fallback reconciliation with callbacks;
for recovery after an outage.

Push

A result with settlement multiplier 1, used for a tied result. Bet status is 23.

A push on an individual bet neither increases nor reduces accumulator odds to zero.

`rate`

Outcome parameter, such as the total or handicap value. Usually 0 when no parameter is required.

`raw_pointer`

The original bet pointer stored unchanged in the complete model.

`real_win`

The actual payout after coupon settlement. Used by the partner for final crediting.

Named realWin in callbacks.

Do not confuse it with potential_win.

Recalculation

A new calculation of a previously settled result.

While waiting:

the coupon has status 15;
the corresponding bet has status 4.

Status 15 is not final.

Settlement

Determination of the bet result and the final coupon payout.

`settlement_reason_code`

A stable machine-readable code for the reason for settlement or return of an individual bet. It may be used for analytics and program logic. The set of values is extensible.

`settlement_reason`

Explanatory text for the reason for settlement or return. It may contain source text from the settlement provider and must not be used as a programmatic identifier.

Sub-event

A related part of the main match: half, period, set, corners, fouls, or another dependent event.

One accumulator cannot contain multiple bets from the same match tree, such as a main match and its corners.

`status`

Numeric object state.

Coupons and bets have different status dictionaries. Interpret the value according to the object level.

Event

A sports match, game, race, or other competition for which a feed is published.

Identified by game_id.

Bet

One accepted outcome within a coupon.

In the complete model it has events_data[].id; in callbacks it has string events_data[].uuid.

Bet Group / Market

A set of related outcomes, for example:

match result;
total;
handicap;
both teams to score.

Identified by bet_group_id.

Outcome

A specific selection within a bet group, such as “First team to win” or “Total over 2.5”.

Identified by bet_id.

End User

A user of the partner system who builds the bet slip and confirms the bet.

SportAPI does not manage this user’s account or balance.

Odds

A numeric value used to calculate the potential payout.

At coupon level:

original_coef — at creation;
coef — current display value;
calculate_coef — final settlement value.

Bet Slip

The user’s preliminary selection before API confirmation.

A bet slip is not an accepted coupon. Store an accepted coupon only after a creation response with code = 1.

Coupon

An accepted bet or set of bets sharing:

coupon_code;
amount;
status;
settlement payout.

Single

A coupon with one bet. It has coupon_type = 1.

Accumulator

One coupon with several bets on different matches. It has coupon_type = 2.

An accumulator may contain no more than 15 events.

Half Win

Bet status 21. Settlement multiplier:

(coef + 1) / 2

Half Loss

Bet status 22. Settlement multiplier:

0.5

Potential Payout

Field potential_win: the potential payout calculated when the coupon is created.

It is not used as the actual credit after settlement.

Bet Pointer

A string that unambiguously describes the selected outcome:

line_type#game_id#group_id#type_id#rate#coefficient[#player_id]

Obtain it from the sports feed and submit it unchanged.

Return

A bet result with settlement multiplier 1.

Bet status is 3. If the entire coupon is returned, coupon status is 8.

Financial Operation

A balance change. The integration has two distinct levels:

SportAPI atomically deducts from the client account balance when a coupon is created;
the partner independently deducts or credits funds to the end user in its own system.

Operations in the partner system must be idempotent so that a repeated callback or polling result does not change the user balance twice.

Next section: Changelog.