Settlement Lifecycle

After a coupon is accepted, the SportAPI Coupon Settlement System tracks the results of all bets included in it and updates the coupon state.

The current result can be received:

• through Client API requests;
• through callbacks, when enabled;
• through both methods at the same time.

Callbacks are optional and do not affect settlement itself. Even if a callback cannot be delivered, the coupon state continues to update and remains available through the API.

General flow

Coupon created
    ↓
Coupon status 0 — active
    ↓
Individual bets are settled
    ↓
┌──────────────────────────────────────────┐
│ All bets are settled                     │
│ → final coupon status 2, 4, or 8         │
└──────────────────────────────────────────┘

Separate branch:
Coupon returned for recalculation
    ↓
Coupon status 15, outcome status 4
    ↓
Waiting for recalculation
    ↓
New current status and a new callback

The coupon status and the statuses of individual bets are different values. For example, a partially settled accumulator may have coupon status 0 even though some of its bets have already been settled.

State immediately after placement

Immediately after successful placement:

The value 0 is not used instead of null for calculate_date.

A coupon remains active until a settlement result becomes available. For an accumulator, status 0 is also used during partial settlement.

Single settlement

A single contains one bet, so it does not have an intermediate settlement of multiple outcomes.

After the bet is settled, the coupon receives one of the final statuses:

If callbacks are enabled, a settlement snapshot is created and sent to the partner after the single is finally settled.

Partial accumulator settlement

An accumulator contains multiple bets that may be settled at different times.

Until a bet loses or all bets have been settled:

• settled bets receive their settlement statuses;
• unsettled bets remain at status 0;
• the coupon remains at status 0;
• its current state is available through the API;
• when callbacks are enabled, a new snapshot of the entire accumulator is sent after each newly settled status.

Example of an accumulator containing five bets:

1/0/0/0/0 → the first bet is settled
1/1/0/0/0 → the second bet is settled
1/1/3/0/0 → the third bet is returned
1/1/3/1/0 → the fourth bet is settled
1/1/3/1/1 → all bets are settled

Each number is the status of an individual bet:

• 0 — not yet settled;
• 1 — win;
• 3 — return.

The first four states are intermediate. The final state completes settlement of the accumulator.

In an intermediate callback:

• the coupon status is 0;
• realWin is 0;
• calculate_coefficient is 0;
• settled bets contain their actual statuses and settlement data;
• unsettled bets remain at status 0.

An intermediate callback is a current snapshot, not the final coupon result.

First losing bet in an accumulator

As soon as at least one bet receives status 2 (LOSE), the entire accumulator becomes a loss:

1/1/2/0/0 → coupon status 4

This happens immediately, even if the remaining bets have not yet been settled.

If callbacks are enabled, the Settlement System immediately sends a snapshot with coupon status 4 (LOSE). This allows the partner to determine that the accumulator has already lost without waiting for every event to finish.

After the first losing bet:

• settlement of the remaining bets continues;
• the current state remains available through the API;
• separate intermediate callbacks for the remaining bets are not sent.

For example:

1/1/2/1/0 → no new intermediate callback is sent

When all bets in the losing accumulator have been settled, the final complete snapshot is sent:

1/1/2/1/3 → final callback

The coupon status remains 4 in both the early and final snapshots, but the final snapshot contains the resulting statuses of all bets.

Final accumulator settlement

Settlement of an accumulator is complete when every bet in it has received a settlement status.

The final status depends on the bet results:

• if at least one bet lost, the coupon receives 4 (LOSE);
• if the coupon did not lose and has a win, it receives 2 (WIN);
• if all bets ended as a return or push, it receives 8 (RETURN).

The return of an individual bet does not make the entire accumulator a return. That bet receives a settlement multiplier of 1 and does not increase the final odds.

Detailed odds, multipliers, and payouts are described in Statuses and payout calculation.

Multiple versions of one coupon

One accumulator may normally be updated several times. Each callback contains a complete settlement snapshot of the coupon at a particular point in time.

Do not confuse these identifiers:

The same coupon_code may therefore arrive:

• in several consecutive callbacks;
• with different bet states;
• with different batchId values.

This does not mean that the coupon was duplicated. The partner must update the existing record by coupon_code and identify a repeated delivery of the same version by batchId.

A new settlement version receives a new batchId. A repeated HTTP delivery of an existing version retains the same batchId.

Deduplication rules are described in detail in Retries and idempotency.

Return for recalculation

A previously settled outcome may be returned for recalculation.

At that point:

1. the coupon receives status 15 (UPDATE);
2. the returned outcome receives status 4 (RECALCULATE);
3. when callbacks are enabled, a snapshot with this state is sent immediately;
4. the coupon waits for recalculation;
5. after recalculation, a new snapshot with the current statuses is sent when callbacks are enabled.

Status 15 is not a final coupon result. For the partner, it means: “Coupon returned for recalculation.”

The name UPDATE is retained for technical compatibility and does not mean a regular data update.

Financial action for status 15

If the previous coupon result has already been processed in the partner’s system, the first receipt of status 15 requires the partner to:

1. debit the stake amount from the user’s balance again;
2. move the local coupon record into a state that waits for a new result;
3. wait for the next settlement status;
4. after receiving the new final result, credit the new real_win value to the user.

The callback does not contain the amount field. The partner must store the amount when the coupon is placed or retrieve the full coupon model through the API.

The repeated debit is performed only once for each new transition of the coupon to status 15. A repeated callback delivery with the same batchId must not cause another debit or credit. When receiving the state through polling, prevent repeated operations by tracking the combination of coupon_code and the status transition already processed.

Required partner-system behavior

1. Store coupon_code as the linking key.
2. Update coupon and bet states when a newer version is received.
3. Do not treat status 0 as the final result of an accumulator.
4. Account for the fact that status 4 may appear before all bets are settled.
5. Do not treat another occurrence of the same coupon_code as an error.
6. On the first transition of an already settled coupon to status 15, debit amount again and wait for the updated result.
7. After the new final result, credit the new real_win value.
8. If necessary, periodically reconcile the state through the API even when callbacks are used.

Next section: Statuses and payout calculation.