Промо-бонусы депозитов (PayIn)

Промо-бонус — маркетинговая механика депозитов: при завершении PayIn-сделки платформа или спонсор акции (мерчант либо провайдер) начисляет бонус поверх обычного нетто мерчанта. Бонус полностью субсидируется спонсором акции — для мерчанта экономика сделки может только улучшиться:

• комиссия мерчанта не меняется — она считается от фактической суммы платежа, промо на неё не влияет;
• бонус приходит тем же назначением, что нетто — отдельного платежа или заявки на получение бонуса нет;
• бонус может не примениться (например, бюджет акции исчерпан) — тогда платёж проходит обычным путём, без промо-полей в раскладке (см. ниже).

Что видит мерчант

Итоговая раскладка приходит в вебхуке deal.completed (только V2): payload несёт объект fee_breakdown — только вашу картину: сумма, ваша комиссия, ваше нетто (+ строка бонуса, если применён промо); детализация внутренних издержек платформы не раскрывается (канон Stripe Connect / Adyen: наружу идут gross, комиссия клиента и его нетто, себестоимость платформы — внутренняя). Про сам вебхук (подпись, доставка, повторы) — раздел Обратный вызов (Callbacks).

Поля объекта fee_breakdown

Все суммы — int64 в USDT-центах, в JSON передаются строками (то же правило proto3 JSON, что и для остальных int64 вебхука):

Внутренние издержки платформы (себестоимость провайдера, доли команды и агентов, удержание платформы) в объекте не раскрываются: наружу идёт только картина мерча — сумма, его комиссия, его нетто.

Промо-строка и когда её нет

Промо-поля (promo_bonus_usdt_cents, promo_id, promo_sponsor_type) присутствуют в объекте только когда промо применён. Во всех остальных случаях объект fee_breakdown всё равно приходит — с картиной мерча, но без промо-полей:

• акция не подходит под платёж (сумма, метод, окно действия) — правило не matched;
• промо skipped — правило matched, но бонус не выплачен (например, бюджет акции исчерпан). Платёж проходит обычным путём, сделка завершается штатно.

Сверка сумм

• promo_bonus входит в общее поступление на баланс мерчанта тем же назначением, что нетто, и отдельно отражается в раскладке — сверяйте поступление как merchant_cut_usdt_cents + promo_bonus_usdt_cents (при применённом промо);
• промо-бонус приходит сверху от спонсора, а не перераспределяет платёж: он не меняет ни gross_usdt_cents, ни вашу комиссию, ни нетто — состав внутренних издержек платформы при этом наружу не раскрывается;
• комиссия мерчанта (merchant_commission_usdt_cents) не зависит от промо — сверяется с тарифом по фактической сумме платежа как раньше.

Примеры payload

deal.completed (PayIn, V2) — с применённым промо (строка promo_* в fee_breakdown):

{
  "event": "deal.completed",
  "deal_id": "7ac148fe-19a3-45bb-b992-019fac55b721",
  "merchant_id": "8f870a31-b88d-4cb0-a882-628d08cbda88",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "150000",
  "currency": "RUB",
  "status": "COMPLETED",
  "timestamp": "2026-09-17T10:00:00Z",
  "received_amount": "150000",
  "amount_match_status": "full",
  "fee_breakdown": {
    "gross_usdt_cents": "150000",
    "merchant_commission_usdt_cents": "2500",
    "merchant_cut_usdt_cents": "147500",
    "promo_bonus_usdt_cents": "750",
    "promo_id": "0f0e0d0c-0b0a-4909-9807-060504030201",
    "promo_sponsor_type": "PLATFORM"
  }
}

Тот же комплит без промо — объект есть, промо-полей нет:

{
  "event": "deal.completed",
  "deal_id": "7ac148fe-19a3-45bb-b992-019fac55b721",
  "merchant_id": "8f870a31-b88d-4cb0-a882-628d08cbda88",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "150000",
  "currency": "RUB",
  "status": "COMPLETED",
  "timestamp": "2026-09-17T10:00:00Z",
  "received_amount": "150000",
  "amount_match_status": "full",
  "fee_breakdown": {
    "gross_usdt_cents": "150000",
    "merchant_commission_usdt_cents": "2500",
    "merchant_cut_usdt_cents": "147500"
  }
}

Версии API

Объект fee_breakdown и промо-строка доступны только мерчантам V2: legacy-конверт V1 новых полей не получает (гейт по api_version), состав V1-уведомлений не меняется. Мигрирующим мерчантам см. раздел Типы уведомлений в адаптере (V1 Compatibility).