Статусы и расчет выплаты

Купон и каждая ставка внутри него имеют собственный статус. Всегда определяйте значение кода с учетом объекта, к которому относится поле status.

Важно. Таблицы статусов купона и ставки различаются. Например, у выигравшего ординара статус купона равен 2, а статус ставки — 1. У проигравшего ординара статус купона равен 4, а проигравшей ставки — 2. Если купон возвращен на перерасчет, статус купона равен 15, а соответствующей ставки — 4.

Статусы купона

Для проигравшего экспресса статус 4 известен до расчета всех ставок, но позже может прийти еще один полный снимок с итоговыми статусами каждого исхода.

Статусы ставки

Расчетный множитель ставки передается:

• в полной модели купона — в events_data[].calc_coef;
• в callback — в events_data[].calculate_coefficient.

Для нерассчитанной ставки и ставки, ожидающей перерасчета, расчетного множителя пока нет.

Поля суммы и выигрыша

Для изменения баланса после финального расчета используйте real_win. Не используйте potential_win как фактическую выплату и не пересчитывайте начисление самостоятельно по отображаемым коэффициентам.

Причина расчета

В полной модели и callback каждая ставка может содержать:

До расчета оба поля равны null. Для программной логики используйте код, а не текст. При этом финансовый результат всегда определяется готовыми status, расчетным коэффициентом и real_win; причина не заменяет эти поля.

Например, при возврате код может пояснить, что матч отменен (MATCH_CANCELLED), перенесен (MATCH_POSTPONED) или рынок рассчитан как push (MARKET_PUSH). Набор кодов расширяемый: неизвестное значение следует сохранить, не отклоняя ответ.

Для уведомления конечного пользователя партнеру рекомендуется локализовать собственный текст по settlement_reason_code. Если код неизвестен, непустой settlement_reason можно показать как запасное пояснение. Не рассчитывайте выплату по тексту причины — используйте готовое значение real_win.

Поля сообщают причину расчета, а не оперативный статус матча. Пока ставка не рассчитана, они остаются null.

В callback поле фактической выплаты называется realWin.

До окончательного расчета:

• сразу после создания в полной модели real_win имеет значение null;
• в промежуточном callback realWin имеет значение 0, но статус купона остается 0.

Текущее значение поля до финального статуса не является окончательной выплатой. Поэтому null в полной модели или 0 в промежуточном callback нельзя считать проигрышем без проверки статуса купона.

Поля коэффициентов купона

В callback поле итогового коэффициента называется calculate_coefficient. В промежуточном callback оно равно 0, потому что окончательный коэффициент еще не сформирован.

Общая логика расчета

Для рассчитанного купона итоговый коэффициент формируется из расчетных множителей ставок:

calculate_coef = factor_1 × factor_2 × ... × factor_n
real_win = amount × calculate_coef

Формула объясняет влияние результатов отдельных ставок. Для финансового начисления используйте готовое real_win, возвращенное API.

Полный выигрыш

Для выигравшей ставки множитель равен ее коэффициенту.

Пример ординара:

amount = 10
coef = 1.85
status ставки = 1
calculate_coef = 1.85
real_win = 18.5
status купона = 2

Пример экспресса с двумя выигравшими ставками:

amount = 10
factor_1 = 1.80
factor_2 = 1.50
calculate_coef = 1.80 × 1.50 = 2.70
real_win = 10 × 2.70 = 27
status купона = 2

Проигрыш

Проигравшая ставка имеет множитель 0. Если хотя бы один исход экспресса проиграл, итоговый коэффициент и выплата всего купона равны 0.

status ставки = 2
calculate_coef = 0
real_win = 0
status купона = 4

Для экспресса статус купона 4 появляется сразу после первого проигравшего исхода, даже если другие ставки еще не рассчитаны.

Возврат

Возвращенная ставка имеет множитель 1.

Для возвращенного ординара:

status ставки = 3
calculate_coef = 1
real_win = amount
status купона = 8

Возврат одного исхода экспресса не возвращает весь купон. Такой исход не увеличивает и не обнуляет общий коэффициент:

factor_1 = 1.80
factor_2 = 1
factor_3 = 1.50
calculate_coef = 1.80 × 1 × 1.50 = 2.70

Если все ставки купона имеют статус RETURN или PUSH, весь купон получает статус 8, итоговый коэффициент равен 1, а real_win равен amount.

Push

PUSH используется при равном результате и имеет тот же расчетный множитель 1, что и возврат:

status ставки = 23
calc_coef = 1

Push отдельной ставки не делает экспресс проигравшим и не увеличивает его итоговый коэффициент.

Половинный выигрыш

Для HALF_WIN расчетный множитель определяется формулой:

factor = (coef + 1) / 2

Пример для коэффициента 2.00:

factor = (2.00 + 1) / 2 = 1.50

При сумме ординара 10 фактическая выплата составит:

real_win = 10 × 1.50 = 15

Статус ставки — 21.

Пример HALF_WIN в экспрессе

Экспресс содержит две ставки:

• первая ставка выиграла с коэффициентом 1.80;
• вторая ставка с коэффициентом 2.00 получила HALF_WIN.

Расчетный множитель второй ставки:

(2.00 + 1) / 2 = 1.50

Расчет всего экспресса при amount = 10:

factor_1 = 1.80
factor_2 = 1.50
calculate_coef = 1.80 × 1.50 = 2.70
real_win = 10 × 2.70 = 27

Исходный коэффициент 2.00 второй ставки не умножается целиком: в расчет экспресса входит уменьшенный множитель 1.50.

Половинный проигрыш

Для HALF_LOSE расчетный множитель всегда равен 0.5.

При сумме ординара 10:

real_win = 10 × 0.5 = 5

Статус ставки — 22.

Пример HALF_LOSE в экспрессе

Экспресс содержит две ставки:

• первая ставка выиграла с коэффициентом 1.80;
• вторая ставка получила HALF_LOSE и множитель 0.5.

Расчет всего экспресса при amount = 10:

factor_1 = 1.80
factor_2 = 0.5
calculate_coef = 1.80 × 0.5 = 0.90
real_win = 10 × 0.90 = 9

HALF_LOSE не обнуляет весь экспресс, как полный проигрыш со статусом 2. Вместо этого множитель 0.5 участвует в произведении вместе с множителями остальных ставок.

Если в этом же экспрессе есть полностью проигравшая ставка с множителем 0, итоговый коэффициент и real_win всего купона будут равны 0.

Перерасчет

При возврате результата на перерасчет:

• купон получает статус 15 (UPDATE);
• соответствующая ставка получает статус 4 (RECALCULATE);
• статус 15 не является финальным;
• после перерасчета приходит новое состояние купона.

Если партнер уже обработал предыдущий результат, при первом получении статуса 15 он должен:

1. повторно списать с пользователя сумму ставки amount;
2. перевести купон в ожидание нового результата;
3. после нового финального статуса начислить новое значение real_win.

Операции выполняются идемпотентно. Повторная доставка callback с тем же batchId не должна повторно списывать или начислять средства.

Callback не содержит amount. Сумму нужно сохранить при создании купона либо получить через API чтения купона.

Десятичные значения и округление

Суммы, коэффициенты и выплаты передаются как десятичные числа без фиксированного количества знаков после запятой:

{
  "amount": 10,
  "calculate_coef": 1.5,
  "real_win": 15
}

API не гарантирует текстовый формат вроде 10.00 или 1.50. Партнер самостоятельно определяет правила округления и отображения значений.

Для изменения баланса используйте полученное значение real_win. Это позволяет не создавать расхождения из-за повторного расчета или отличающихся правил округления.

Следующий раздел: «Callback результатов».