ППополнениеПанель управления ↗
Пополнение · API v1.6.0

Приём платежей на вашем сайте

Покупатель оплачивает счёт в рублях через СБП. Продавец Stars зачисляет Stars на выделенный аккаунт. Аккаунт оплачивает отдельный счёт Радара. Обычные платежи зачисляются мерчанту автоматически по подтверждённой квитанции. Для платежа с апелляцией требуется отдельное ручное решение модератора.

Какие поля использовать

В основном потоке сохраните id и external_id и проверяйте status. При payment_url_kind: "checkout" сразу открывайте покупателю payment_url, в том числе при queued/creating: наша форма сама дождётся реквизитов. WILDER ORIGINAL получают нашу форму сразу: новый запрос возвращает HTTP 200 без ожидания котировки; в REST и обычных webhook поле status равно awaiting_payment, payment_url ведёт на bonbonus.fun, payment_url_kind равно checkout. Этот статус означает доступность формы; котировка и реквизиты провайдера могут ещё готовиться. Форму открывайте сразу, даже если stars и payer_amount равны null. Для остальных мерчантов без нашей формы прямые ссылки с типом provider или nspk показывайте только при awaiting_payment вместе с полной payer_amount. Исполняйте заказ только после проверенного payment.paid или подтверждённого через API статуса paid. payment.cancelled завершает неудачную подготовку ссылки.

Paradise, Horizon и Vault используют прежний порядок прямой выдачи: новый запрос возвращает HTTP 202, идемпотентный повтор — HTTP 200. На этапе queued/creating payment_url=null. После готовности возвращаются awaiting_payment, проверенная ссылка provider/nspk в payment_url и payer_amount. Ссылка на нашу форму вместо реквизитов не подставляется; checkout_url отсутствует. Оплата подтверждается только статусом paid.

creation_deadline_at нужен только для обратного отсчёта, cancellation_reason — для пояснения причины отмены. Обрабатывать эти два дополнительных поля необязательно. Они сохранены для совместимости; поля, которые не использует ваш сайт, можно игнорировать. Общий срок подготовки — 55 секунд, но уже готовая ссылка продолжает ждать оплаты. Дубликаты webhook обрабатывайте однократно по event.id, подлинность проверяйте по подписи ниже.

Баланс и выплаты — в XTR (Telegram Stars). Для рублёвого заказа передайте amount_rub: целое число от 100 до 50 000. При подборе Stars допускается сумма на 1 ₽ ниже запроса, но не ниже 100 ₽: исходный интервал — от max(100, amount_rub − 1) до amount_rub + 0.99 включительно. Например, 310 ₽ означает 309,00–310,99 ₽; для 100 ₽ остаётся 100,00–100,99 ₽. При занятых количествах Stars подбирается следующее свободное количество: N, N+1, N+2 и далее, в пределах, поддерживаемых методом, что может повысить итог по свежей котировке продавца. До оплаты покупатель видит полную сумму с копейками. Stars продаются целыми, курс меняется; если подходящей суммы нет, ссылка не выдаётся.

Каскад получения реквизитов

Новые запросы мерчантов автоматически используют общий каскад доступных продавцов и способов оплаты. Первый приоритет — @stars · СБП: после его котировки сразу создаётся счёт, без ожидания остальных продавцов. При отказе до отправки создания счёта рассматриваются другие доступные методы. После отказа @stars каскад последовательно пробует остальные разрешённые методы и сразу использует первую готовую котировку; предварительная котировка отмечается отдельно. При подтверждённом отказе до создания счёта выбирается следующий подходящий метод. Несовместимые суммы, неподготовленные аккаунты и неподтверждённые способы пропускаются. После выдачи ссылки способ закрепляется за платежом. Для новых заявок получение НСПК и обращение к API платёжной страницы не требуются: выдаётся сама страница продавца. Оплата подтверждается только по связанному поступлению Stars и внутренней квитанции; ссылка не означает успешную оплату.

Таймаут после отправки запроса на создание не означает, что счёта нет. При неопределённом результате система сохраняет попытку для сверки и не создаёт повторный счёт. Ограничитель выдачи и апелляция действуют на весь каскад. Общий срок подготовки остаётся 55 секунд; переключение способа не запускает таймер заново.

В ответе может появиться дополнительный объект routing с выбранным способом и безопасной историей попыток. Для интеграции достаточно прежних полей status, payment_url, payer_amount. Промежуточные котировки не являются реквизитами для оплаты. Повторяйте тот же запрос с исходным Idempotency-Key.

В панели режим Каскад · сначала @stars использует все совместимые методы. Выбор Только … ограничивает диагностику указанным продавцом. Тестовое получение выполняет тот же процесс и создаёт настоящий счёт в «Ручных платежах», без webhook мерчанту. Автоматически оплачивать такой счёт система не будет; если оплатить вручную, поступление учитывается обычным порядком. Это не sandbox.

Ссылка вручную, без интеграции

В панели выберите Получить ссылку, оставьте режим Рубли, задайте целевую сумму и нажмите Создать ссылку. Итог может быть на 1 ₽ ниже запроса, но не ниже 100 ₽. При занятом количестве Stars добавление Stars может повысить сумму. Полный расчёт появится до оплаты. В режиме Stars действует прежний ввод: от 100 до 35 000, шаг 100. По умолчанию счёт относится к «Ручным платежам»; можно выбрать активного мерчанта. Номер заказа и описание необязательны.

После ответа на создание доступна ссылка на страницу оплаты. Для @stars выдаётся связанная страница kassa.ai, для Rocket — AuraPay, для Barboskich — Wata: предварительная сумма помечена в API, окончательная показана на странице продавца перед оплатой. Если соединение прервалось, используйте Повторить получение того же счёта: запрос сохраняется в текущей вкладке. Ссылка и подтверждения также доступны в истории платежей. Кнопка «Новый счёт» оставляет предыдущий счёт в истории.

В обзоре доступны периоды 7, 30 и 90 дней с фильтром мерчанта. Конверсия — доля оплаченных из счетов, созданных за этот период; поступления Stars и рублей учитываются по фактической дате оплаты. Фильтры истории и CSV используют дату создания в Москве. Выгрузка ограничена 10 000 строками — при превышении сузьте период.

Подготовка частых сумм

В панели Платежи → Быстрая выдача ссылок администратор может включить подготовку меню для одной или двух частых рублёвых сумм. Готовность обновляется на открытой вкладке раз в 10 секунд. При подготовленном свободном аккаунте цель — выдача ссылки за 5–10 секунд; это не гарантия времени ответа Telegram и провайдера. Для остальных сумм или при отсутствии готового аккаунта используется обычная очередь.

Предварительно открывается только меню продавца Stars: банковский счёт создаётся после запроса покупателя. Подготовка не оплачивает счета. Перед выдачей проверяются получатель, количество Stars и котировка продавца; для прямой НСПК — также фактическая сумма. Ссылку нельзя показывать, пока она не появилась в ответе платежа.

1. Создайте мерчанта

Откройте bonbonus.fun/admin, войдите по одноразовому коду из личного уведомления Радара и выберите Мерчанты → Добавить мерчанта. Сохраните выданный API-ключ и отдельный секрет webhook. Ключ API показывается один раз, храните его только на сервере сайта. Публичной регистрации нет: мерчантов создаёт администратор.

BASE_URL — https://bonbonus.fun. Базовый путь API: /api/merchant/v1. Наша форма оплаты для WILDER ORIGINAL расположена на https://bonbonus.fun/pay/…, для отдельного мерчанта Wilder — на https://bn.softapi.org/pay/…. Домен bn.softapi.org не используется как базовый адрес Merchant API. Не передавайте ключ в браузер, URL, аналитические события или логи.

2. Создайте платёж с сервера сайта

curl "$BASE_URL/api/merchant/v1/payments" \
  -H "Authorization: Bearer $RADAR_API_KEY" \
  -H "Idempotency-Key: shop-order-1042" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"flowers-1042","amount_rub":100,"description":"Заказ цветов №1042","callback_url":"https://shop.example.com/hooks/payments","metadata":{"cart_id":"c-42"}}'

Webhook для отдельного заказа. Необязательный параметр callback_url передаётся в JSON при создании платежа. Если задан непустой адрес, все webhook этого заказа отправляются на него вместо адреса мерчанта. Если поле отсутствует, равно null или пустой строке, используется webhook из настроек мерчанта. Требуется публичный HTTPS URL на порту 443, без логина и фрагмента. Подпись и секрет остаются мерчантовскими. Адрес закрепляется за заказом: изменение callback_url при повторе с тем же Idempotency-Key или external_id возвращает 409 idempotency_conflict.

Передавайте ровно одно поле: amount_rub (целые рубли, 100–50 000) или stars (100–35 000, кратно 100). Оба поля вместе, дробная сумма или отсутствие обоих полей отклоняются. В рублёвом режиме Stars ещё неизвестны при создании: сначала stars: null, затем выбранное целое количество, от 50 до 35 000. Правило кратности 100 относится только к прямому запросу в Stars.

Новый запрос любого мерчанта возвращает 202. Проверяйте поля status и payment_url_kind. Для Wilder и WILDER ORIGINAL ответ возвращается сразу. У WILDER ORIGINAL в REST создания, списка и получения платежа и в обычных webhook при доступной форме без апелляции возвращается status: awaiting_payment, payment_url нашей формы https://bonbonus.fun/pay/… и payment_url_kind: checkout. Поля checkout_url и processing_status не добавляются. Здесь awaiting_payment означает готовность нашей формы к открытию, а не готовность котировки или реквизитов провайдера: stars и payer_amount могут оставаться null. Реальный этап подготовки отображается внутри формы и в админке. После готовности реквизитов в той же форме появится кнопка оплаты. В терминальных статусах и при апелляции эта подмена статуса не применяется, платёжная ссылка не выдаётся. У отдельного мерчанта Wilder форма находится на https://bn.softapi.org/pay/…, тип — checkout, а дополнительное поле checkout_url содержит тот же адрес. stars в рублёвом режиме и payer_amount могут быть null до подбора и котировки. Для остальных мерчантов создание по-прежнему ожидает готовые реквизиты до 8 секунд: при awaiting_payment возвращается прямая ссылка и сумма; при queued/creating прямая payment_url пока null. Продолжайте получать GET /payments/{id} раз в секунду при queued/creating и раз в 5 секунд при awaiting_payment. Учитывайте общий лимит 120 запросов в минуту на мерчанта вместе со всеми другими API-запросами: для нескольких платежей увеличивайте интервал. Ни 200, ни 202 в ответе создания не подтверждают готовность реквизитов или оплату. Повтор того же запроса с тем же Idempotency-Key возвращает 200 и прежний платёж. Один external_id принадлежит одному заказу мерчанта. Изменённый запрос с тем же ключом или номером заказа даёт 409 idempotency_conflict. При сетевом сбое повторяйте прежний ключ, не создавайте новый.

Пример первого ответа мерчанту без нашей формы:

{
  "id": "7d…", "external_id": "flowers-1042", "amount_rub": 100, "stars": null,
  "status": "queued", "currency": "XTR", "payer_currency": "RUB",
  "payer_amount": null, "payment_url": null,
  "checkout_path": "/pay/…", "metadata": {"cart_id":"c-42"},
  "created_at": 1792410000.0, "updated_at": 1792410000.0, "paid_at": null,
  "description": "Заказ цветов №1042", "issue": ""
}

ID покупателя — необязательное поле user_id

При создании платежа можно передать "user_id":"customer-42" отдельным полем JSON. Допускаются строка от 1 до 128 символов без пробелов по краям и управляющих символов или положительное целое число до 9223372036854775807. Числовое значение сохраняется как строка.

{"external_id":"order-1042","amount_rub":150,"user_id":"customer-42"}

ID покупателя сохраняется в metadata.user_id и возвращается отдельным user_id в ответах merchant API. В callbacks он доступен в data.metadata.user_id. При повторном поиске реквизитов ID сохраняется. Это ID покупателя у мерчанта, отдельный от Telegram-аккаунта исполнителя.

Поле необязательно: без него действующий запрос работает как прежде; null означает отсутствие значения. Другие поля metadata сохраняются. Если указаны оба поля user_id и metadata.user_id, их значения должны совпадать. Некорректное значение возвращает HTTP 400 с кодом invalid_user_id.

Передавайте ID при создании новой заявки. Содержимое одной заявки, включая ID покупателя, должно оставаться неизменным при повторе с тем же external_id или Idempotency-Key. Поле само по себе не вводит лимитов на заявки покупателя.

Статистика покупателя — необязательный объект user_stats

В POST /api/merchant/v1/payments можно передать статистику этого покупателя по истории вашего сервиса. Все четыре поля независимы и необязательны; user_id также остаётся необязательным. Дневные показатели относятся к текущему календарному дню по Москве (Europe/Moscow, UTC+3), до создания текущей заявки. Итоговый оборот считается за всё время в рублях.

Поле внутри user_statsЗначениеТип
unpaid_orders_todayСколько заявок пользователя, созданных за день, не оплаченоЦелое число от 0 до 2147483647
stars_purchase_turnover_total_rubОбщий оборот пользователя на покупку Stars за всё время, RUBЧисло или десятичная строка, от 0 до 999999999999.99, максимум два знака после точки
stars_sale_turnover_total_rubОбщий оборот пользователя на продажу Stars за всё время, RUBЧисло или десятичная строка, от 0 до 999999999999.99, максимум два знака после точки
successful_topups_todayСколько успешных заявок на пополнение было у пользователя за деньЦелое число от 0 до 2147483647
{
  "external_id": "stars-order-1042",
  "amount_rub": 150,
  "user_id": "customer-42",
  "user_stats": {
    "unpaid_orders_today": 3,
    "stars_purchase_turnover_total_rub": "12500.50",
    "stars_sale_turnover_total_rub": "3200.00",
    "successful_topups_today": 2
  }
}

Передавайте любые из четырёх полей. Пропуск, null и пустой объект означают отсутствие данных; явный ноль сохраняется как ноль. Отсутствующие значения не дополняются нулями. Денежные значения сохраняются и возвращаются строкой с двумя знаками после точки, например "12500.50". Логические значения, отрицательные суммы, дробные счётчики и неизвестные поля объекта отклоняются с HTTP 400, invalid_user_stats.

Снимок сохраняется в metadata.user_stats. В ответах создания, получения и списка merchant API он также доступен отдельным user_stats; в callbacks — data.metadata.user_stats. При повторном поиске реквизитов снимок сохраняется. Другие поля metadata сохраняются, общий действующий лимит metadata — 2048 символов. Если одновременно переданы user_stats и metadata.user_stats, после нормализации они должны совпадать.

Снимок относится к конкретной заявке. При повторе с тем же external_id или Idempotency-Key отправляйте исходные значения, даже если статистика уже изменилась: изменение снимка возвращает обычный 409 idempotency_conflict. В новую заявку можно передать обновлённый снимок.

Это сведения мерчанта о покупателе, а не подтверждённый оборот платёжной системы. Они не меняют сумму оплаты, баланс, зачисление, статус заявки или правила каскада. Запросы без user_stats продолжают работать как раньше.

3. Откройте страницу оплаты

Для новых заявок каскад начинается с @stars · СБП: общий бюджет этого метода — 15 секунд на расчёт и получение ссылки. При отказе или истечении бюджета до отправки создания счёта следующий метод — Krab.gg. Если создание уже отправлено и результат неизвестен, система сверяет исходный счёт; второй счёт вслепую не создаётся. Общий срок подготовки каскада остаётся 55 секунд.

Комиссия Krab.gg. Krab.gg: запрошенная amount_rub сохраняется. Комиссия и округление СБП прибавляются сверху после проверки счета продавца. seller_amount_rub — стоимость Stars до доплаты; provider_surcharge_rub — доплата и округление; provider_surcharge_policy=added_on_top. payer_amount — итог счета, effective_amount_rub — его целые рубли; payer_amount_source=seller_checkout. Это подтверждённая цена счета, а не банковская квитанция: payer_amount_is_estimate=true сохраняется. Успех требует фактического поступления и зачисления Stars. Новые дополнительные поля также передаются в webhook. payment_url может вести на gate.antilopay.com. Клиент должен видеть итоговую сумму до перехода к оплате.

Обновление API 1.7.1. Для новых платежей через @stars требуется прямая НСПК: payment_url_kind=nspk, payer_amount_is_estimate=false. Бюджет @stars — 30 секунд, общий срок создания — 55 секунд. Остальные продавцы могут выдавать свою платёжную страницу: payment_url_kind=provider, payer_amount_is_estimate=true. Сумма payer_amount в этом режиме — предварительная котировка продавца, не доказательство списания рублей; итог отображается на странице провайдера. Для прямой НСПК payment_url_kind=nspk, payer_amount_is_estimate=false. После выдачи ссылки 55-секундный срок создания больше не отменяет заявку. payment.paid по-прежнему требует подтверждённого поступления и зачисления Stars. Не считайте котировку подтверждённой рублёвой выручкой. Показывайте покупателю знак «≈» и переход на страницу провайдера; успех определяйте по подписанному payment.paid. Эти поля также передаются в webhook. Старые выданные ссылки сохраняются.

Для мерчанта с нашей формой направьте покупателя на payment_url с типом checkout сразу после создания, даже если реквизитов ещё нет. Форма сама опрашивает состояние и после готовности показывает кнопку «Открыть страницу оплаты», ведущую на страницу продавца. Открывайте её обычным переходом или в отдельном окне; встраивание в iframe не поддерживается. Для остальных мерчантов используйте прямую payment_url после awaiting_payment. checkout_path — относительный путь формы; он не подтверждает ни готовность реквизитов, ни оплату. Если используете собственную страницу, получайте статус по ID раз в секунду при queued/creating, раз в 5 секунд при awaiting_payment и collecting. Общий лимит — 120 запросов в минуту на мерчанта, включая все остальные API-запросы. Опрос выполняйте централизованно на сервере магазина; при нескольких активных платежах увеличивайте интервалы, а при HTTP 429 соблюдайте Retry-After. Проверка готовности и суммы перед показом прямой ссылки provider/nspk: status: awaiting_payment и совпадение целых рублей с effective_amount_rub (для старых ответов без этого поля — с amount_rub). Ссылку нашей формы с типом checkout разрешено открывать раньше; проверку реквизитов выполняет сама форма. Поле payer_amount — десятичная строка; для денежных расчётов используйте Decimal или целые копейки. Тип назначения указан в payment_url_kind: checkout — наша форма, provider — страница продавца/провайдера, nspk — НСПК. Тип checkout не означает готовность реквизитов или успешную оплату; те же правила представления ссылки действуют в webhook этого заказа. Истечение счёта подтверждается ответом провайдера. Ошибка сети не означает истечение или успех.

Исходное amount_rub сохраняется неизменным. Сначала ищем свободный аккаунт и Stars для исходного интервала с допуском до 1 ₽ вниз. Поле effective_amount_rub всегда равно целой части свежей котировки выбранных Stars, в том числе при quantity_adjustment: 0. Поэтому для запроса 310 ₽ оно может быть 309. После выбора котировки сумму провайдера проверяем строго в интервале от effective_amount_rub до effective_amount_rub + 0.99, а не по всему исходному интервалу.

Если на аккаунте уже ожидает оплаты такое количество, выбираем следующее свободное: N+1, N+2, N+3 Stars и далее, до первого свободного количества в диапазоне метода. Это шаг в Stars, поэтому рост в рублях зависит от продавца. Метод @stars «СБП №2» принимает только количества, кратные 100: неподдерживаемый шаг +1 для него не отправляется, каскад рассматривает другой подходящий метод; в этом режиме итоговый интервал начинается не ниже исходного amount_rub. На одном аккаунте допускается до 10 отдельных резервов. Пример: запрос 100 ₽, количество 66 занято, выбрано 67 Stars; возможный ответ — effective_amount_rub: 101, quantity_adjustment: 1, payer_amount: "101.66", amount_adjustment_rub: "1.66". Это пример, а не фиксированный курс. Покупатель должен видеть полную сумму 101,66 ₽ до оплаты; в успешном webhook и статистике будет фактически оплаченная сумма. Если источник или сумма не подтверждены, ссылка не выдаётся.

Изменение для интеграции v1.4: итог без дополнительных Stars может быть на 1 ₽ ниже запроса, с минимумом 100 ₽. Например, amount_rub: 310, effective_amount_rub: 309, quantity_adjustment: 0, payer_amount: "309.56", amount_adjustment_rub: "-0.44". Разница может быть отрицательной. При добавлении Stars итог по-прежнему может повышаться. Не заменяйте amount_rub фактической суммой: храните исходный запрос отдельно, показывайте payer_amount целиком и проверяйте её против effective_amount_rub. Баланс мерчанта учитывает фактически подтверждённые Stars, рублёвые webhook и статистика — фактическую сумму.
curl "$BASE_URL/api/merchant/v1/payments/PAYMENT_ID" \
  -H "Authorization: Bearer $RADAR_API_KEY"

4. Подтвердите заказ по webhook

WILDER ORIGINAL: форма доступна сразу. В REST создания, списка и получения платежа и в обычных webhook при доступной форме без апелляции возвращается status: awaiting_payment, payment_url нашей формы bonbonus.fun и payment_url_kind: checkout. До фактической готовности котировки поля stars и payer_amount могут быть null. Открывайте форму сразу; реальную подготовку реквизитов она показывает сама. Обычное событие доступной формы имеет тип payment.awaiting_payment; это не подтверждение получения реквизитов провайдера, оплаты или зачисления. При реальной готовности реквизитов может прийти новое событие с тем же типом и другим event.id; обрабатывайте события по их ID. Статусы в базе, суммы, бухгалтерский учёт и подтверждение paid не изменяются. В остальных статусах и при апелляции платёжная ссылка отсутствует; реальный статус сохраняется. Поля checkout_url и processing_status не добавляются. Уже созданные webhook-события не переписываются и сохраняют первоначальные данные. У отдельного мерчанта Wilder форма остаётся с типом checkout и полем checkout_url в REST и обычных webhook. Подтверждение оплаты — только paid.

Endpoint мерчанта должен быть доступен по HTTPS на 443 и принимать POST JSON. Локальные и служебные адреса запрещены; перенаправления не выполняются. Система проверяет DNS и соединяется с проверенным публичным IP, сохраняя имя TLS.

Заголовки: X-Radar-Event-Id, X-Radar-Timestamp (Unix-секунды), X-Radar-Signature: v1=HEX. Подпись: HMAC-SHA256(secret, timestamp + "." + исходные байты тела). Не пересериализуйте JSON перед проверкой.

{"id":"event-id","type":"payment.paid","created_at":1792410123,
 "data":{"id":"payment-id","external_id":"flowers-1042","amount_rub":100,
         "payer_amount":"101.66","stars":67,"effective_amount_rub":101,
         "quantity_adjustment":1,"amount_adjustment_rub":"1.66",
         "currency":"XTR","status":"paid","paid_at":1792410120,...}}

Пример проверки на Python:

import hashlib, hmac, time

def verify(headers, raw_body, secret):
    try:
        timestamp = headers["x-radar-timestamp"]
        if abs(time.time() - int(timestamp)) > 300:
            return False
        received = headers["x-radar-signature"]
        expected = "v1=" + hmac.new(
            secret.encode(), timestamp.encode() + b"." + raw_body,
            hashlib.sha256).hexdigest()
        return hmac.compare_digest(received, expected)
    except (KeyError, ValueError):
        return False

# После проверки подписи:
# 1. Сохраните event.id в БД с UNIQUE-ограничением.
# 2. Сверьте payment ID, external_id, currency и параметры заказа.
#    Для RUB: amount_rub равен исходному запросу и не меняется.
#    quantity_adjustment — добавленные Stars (0..10).
#    При 0: max(100, amount_rub - 1) <= effective_amount_rub <= amount_rub.
#    При quantity_adjustment > 0: amount_rub <= effective_amount_rub <= 50000.
#    Целые копейки payer_amount должны попадать строго в
#    effective_amount_rub * 100 ... effective_amount_rub * 100 + 99.
#    amount_adjustment_rub может быть отрицательным; сохраняйте
#    payer_amount как полную фактически оплаченную сумму.
#    Для Stars: stars должны равняться количеству в запросе.
# 3. Для payment.paid подтвердите заказ ровно один раз.
# 4. Транзакционно сохраните изменение, верните HTTP 200.
# Для дубликата также верните 200.

Node.js (используйте исходный Buffer запроса):

import crypto from 'node:crypto';
function verify(headers, rawBody, secret) {
  const ts = headers['x-radar-timestamp'];
  if (!/^\d+$/.test(ts || '') || Math.abs(Date.now()/1000 - Number(ts)) > 300) return false;
  const expected = 'v1=' + crypto.createHmac('sha256', secret)
    .update(ts + '.').update(rawBody).digest('hex');
  const actual = String(headers['x-radar-signature'] || '');
  return actual.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(actual), Buffer.from(expected));
}

Доставка — не менее одного раза: возможны дубликаты и события не по порядку. Не понижайте уже подтверждённый заказ по запоздалому событию. Для спорного события запросите актуальный платёж через API. Успех доставки — любой 2xx. При ошибке повторяем до 12 попыток с увеличением задержки (30 секунд, 60, 120… до 6 часов). В панели доступен ручной повтор с тем же event.id. Старые события хранят исходный снимок статуса.

При смене секрета новые события подписываются новым секретом; ожидающие события сохраняют старую версию. На переходный период принимайте оба секрета. Ручной повтор использует текущий URL и секрет. Новый API-ключ можно выдать до отзыва старого, чтобы обновить интеграцию без остановки.

Апелляции: успех только после ручного решения

Покупатель может подать апелляцию со страницы оплаты. Администратор — во вкладке Апелляции или из карточки платежа. Сайт мерчанта использует POST /payments/{id}/appeals. Нужны описание проблемы и, при наличии, данные из квитанции:

curl "$BASE_URL/api/merchant/v1/payments/PAYMENT_ID/appeals" \
  -H "Authorization: Bearer $RADAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Оплатил, но заказ не подтверждён","evidence":"Номер операции из квитанции, сумма и время"}'

message — от 5 до 1000 символов; evidence — необязательный текст до 1000 символов. Не передавайте банковские коды, пароли или полные реквизиты карты. Файлы этим методом не принимаются. Для одного платежа создаётся одна апелляция: повторный запрос возвращает существующую и не создаёт повторное зачисление. Отдельный Idempotency-Key для апелляции не нужен. Устаревший POST /payments/{id}/issues работает как алиас этого метода.

{"appeal":{"id":"appeal-id","status":"pending",
  "created_at":1792410123,"decided_at":null,"decision_comment":""},
 "created":true}

В ответе на получение платежа доступны appeal (объект или null) и can_appeal. Уже оплаченный платёж нельзя перевести в апелляцию. Статусы апелляции: pending — ожидает решения; approved — одобрена; rejected — отклонена. Проверяйте состояние через GET раз в 5–10 секунд; не предлагайте покупателю повторно оплатить счёт на проверке.

После принятия апелляции по этому платежу не отправляются автоматические callbacks. Подача и отклонение апелляции также не отправляют callback. Единственное разрешённое событие — payment.paid после ручного одобрения модератором в отдельном Telegram-боте. Обычные платежи без апелляций подтверждаются автоматически по прежней схеме. События, уже доставленные до обращения, отозвать нельзя.

Доступ к боту модерации выдаётся по Telegram ID. Модератор проверяет платёж и подтверждает решение в боте. Сайт и Merchant API не имеют кнопки или метода самостоятельного одобрения. В журнале сохраняются модератор, время и комментарий. При одобрении статус платежа становится paid, а событие содержит отметку о ручном решении:

{"type":"payment.paid","data":{"id":"payment-id",
  "status":"paid","stars":100,"currency":"XTR",
  "approval":{"mode":"manual","appeal_id":"appeal-id",
              "moderator_id":123456789,"decided_at":1792410900}}}

Ручное одобрение — отдельная учётная корректировка, за которую отвечает модератор. Оно не является технической квитанцией о фактическом поступлении Stars и само не выполняет перевод. Зачисление мерчанту защищено от дублей. Если подтверждение поступления придёт позднее, повторного зачисления не будет. Проверяйте подпись события и обрабатывайте его ID один раз так же, как для обычной оплаты.

Для новых заявок creation_deadline_at = created_at + 55: срок включает очередь, котировки, подготовку в Telegram и получение QR. Все переключения и чтения используют только оставшееся время. Перезапуск, повтор API и ручная сверка не продлевают срок. Если ссылка готова вовремя, таймер подготовки завершается: на оплату остаётся обычный срок счёта провайдера. cancelled означает отмену подготовки в нашей системе; данные существующего внешнего счёта сохраняются для проверки позднего поступления. Саму внешнюю оплату этот таймер не аннулирует. Исторические заявки с creation_deadline_at: null сохраняют прежний порядок; апелляции решаются модератором.

Статусы и проблемные платежи

СтатусЧто делать сайту
queuedОжидать свободного аккаунта. Если payment_url_kind=checkout, форму можно открыть сразу. Очередь включена в общий срок подготовки 55 секунд; по его истечении заявка станет cancelled.
creatingСоздаётся счёт продавца Stars. При payment_url_kind=checkout форма уже доступна и сама ждёт реквизиты. Не дублировать запрос.
awaiting_paymentДля WILDER ORIGINAL с payment_url_kind=checkout доступна наша форма; котировка и реквизиты провайдера могут ещё готовиться, stars и payer_amount могут быть null. Откройте форму сразу: она покажет подготовку, затем кнопку оплаты. У остальных мерчантов реквизиты готовы: прямую payment_url показывайте с полной payer_amount. Заказ ещё не оплачен.
collectingStars поступили, ожидается квитанция Радара.
paidStars зачислены мерчанту. Можно исполнять заказ сайта.
expiredПровайдер подтвердил истечение. Позднее поступление переводится в review; не оплачивать снова тот же счёт.
reviewРезультат неоднозначен. Оператор проверяет журнал, квитанции и поступления. Автоматическое повторное списание запрещено.
cancelledСсылка не подготовлена за 55 секунд. payment_url=null; приходит payment.cancelled, cancellation_reason=creation_timeout. Старую ссылку не оплачивать. Новая заявка требует новых external_id и Idempotency-Key.
failedСчёт не создан. Для нового заказа используйте новые external_id и Idempotency-Key.

В панели администратор видит ID провайдера, поступление Stars, счёт Радара, временные метки, журнал и webhook-попытки. Кнопка сверки проверяет реальные подтверждения. Если есть апелляция, сверка не обходит решение модератора: успех отправляется только после ручного одобрения в Telegram. Апелляция не отменяет уже подтверждённую оплату.

Подтверждённое истечение освобождает резерв аккаунта, но количество Stars неоплаченного счёта остаётся занятым на час от момента выставления продавцом (issued_at). Повторное использование допускается не раньше issued_at + 3600 и только при подтверждённом истечении, без признаков поступления, перевода или нерешённой сверки. До этого можно использовать другие свободные количества. Срок действия ссылки задаёт продавец: часовая бронь его не продлевает, истёкшую ссылку оплачивать не нужно. Если реальная квитанция Telegram подтверждает поступление не позднее часовой границы (received_at <= issued_at + 3600), поздно обнаруженный платёж может продолжить обычную автоматическую обработку при однозначной связи аккаунта, количества Stars и счёта, даже если к моменту проверки ссылка уже истекла. Учитывается время поступления из квитанции, а не время опроса. Если счёт продавца остаётся действующим, обычная обработка поступления после часа не меняется. Успех и webhook отправляются после штатного подтверждения зачисления; один баланс аккаунта не является подтверждением. Поздние поступления по истёкшим счетам за пределами часа, неоднозначные связи и апелляции требуют ручной сверки. История сохраняется: старый конкурирующий счёт внутри часа не исключается только потому, что его ссылка истекла. В журнале записываются основания освобождения, времена и варианты сопоставления; пароли и ключи не записываются. Неоднозначный отправленный счёт без полученного ID удерживает аккаунт до сверки. При рассмотрении апелляции проверяйте подтверждения провайдера и журнал — одного скриншота, суммы или времени недостаточно для достоверной сверки. Возврат банковской оплаты решается с продавцом Stars; возврат Stars — отдельная операция. Автоматических банковских возвратов в API нет.

Список, статистика и баланс

МетодНазначение
GET /payments?limit=50&offset=0&status=paidПлатежи только вашего мерчанта; лимит 1–100. Дополнительный фильтр external_id.
GET /statisticsЧисло и сумма по статусам, оплаченные поступления за 30 дней, дни по МСК.
GET /balanceДоступный баланс XTR после резервирования выплат.
GET /payoutsИстория заявок на выплаты.

Выплаты в Stars

curl "$BASE_URL/api/merchant/v1/payouts" \
  -H "Authorization: Bearer $RADAR_API_KEY" \
  -H "Idempotency-Key: payout-2026-001" \
  -H "Content-Type: application/json" \
  -d '{"stars":500,"destination":"Согласованные реквизиты мерчанта"}'

Система резервирует Stars из доступного баланса и создаёт заявку requested. Администратор исполняет выплату отдельно согласованным способом и сохраняет подтверждение: paid. При rejected резерв возвращается ровно один раз. Кнопка подтверждения не выполняет перевод. Самостоятельного прямого вывода Stars из баланса бота на произвольный аккаунт API не обещает. Статус выплаты проверяйте через GET /payouts.

Автоматическая остановка выдачи

Автоматическая остановка по числу ошибок отключена владельцем. Ошибки и задержки продолжают журналироваться; администратор может приостановить выдачу вручную. Создание нового платежа возвращает HTTP 503 с кодом issuance_paused. Повтор с прежним Idempotency-Key возвращает существующую заявку. Уже выданные счета, проверка поступлений, зачисления и webhooks продолжают работать. Не создавайте новый заказ вместо уже выданного счёта. Возобновление доступно только администратору после проверки причины; оно не происходит автоматически через 15 минут.

Ошибки, ограничения и восстановление

{"error":{"code":"idempotency_conflict","message":"…"},"detail":"…"}

400 — неверные поля; 401 — ключ отсутствует или отозван; 404 — заказ отсутствует или принадлежит другому мерчанту; 409 — конфликт/недостаток баланса; 429 — лимит (Retry-After: 60); 503 — модуль недоступен или issuance_paused: выдача новых реквизитов приостановлена. До 120 API-запросов в минуту на мерчанта. Общего ограничения на число активных заказов нет. Конкретное количество Stars резервируется на Telegram-аккаунте на час с момента создания счёта продавца. Если количество занято, система пробует следующее: +1 Star. Итоговая сумма может увеличиться: показывайте покупателю payer_amount и effective_amount_rub перед оплатой. После часа освобождается резерв суммы, а история счёта сохраняется для проверки поздних поступлений. Неоднозначное поступление требует сверки и не зачисляется двум заявкам. Объект metadata — до 2048 символов; тело запроса — до 8192 байтов. Не передавайте персональные или платёжные секреты в metadata.

После перезапуска заявки, ключи, баланс, резервы и webhook-очередь восстанавливаются из SQLite. Сохраняйте резервную копию stars_purchase.sqlite3 вместе с merchant-signing.key; ключ подписи не входит в публичный архив исходников. Рабочие API-ключи хранятся только в виде хешей. Внешние ошибки записываются типом исключения без секретов.

Проверка перед подключением магазина

Создайте отдельного мерчанта, отправьте один заказ с amount_rub: 100 и проверьте исходный amount_rub, выбранные Stars, effective_amount_rub и полную payer_amount. При добавлении Stars итог может превышать 100,99 ₽. Тестового денежного режима нет: это реальный счёт, оплачивайте его только осознанно. Убедитесь, что сайт исполнил заказ после payment.paid, повтор webhook не исполнил его снова, а неверная подпись отклоняется. Проверьте недоступный интервал, сетевой повтор с тем же ключом и восстановление stars: null. Не считайте HTTP 200/202 в ответе создания или переход покупателя обратно на сайт подтверждением платежа. Проверьте также заказ 310 ₽ с итогом 309,56 ₽, effective_amount_rub: 309 и отрицательной разницей −0,44 ₽. Сумма 308,99 ₽ для такого запроса и 99,99 ₽ для запроса 100 ₽ недопустимы. На сайте заранее укажите допуск до 1 ₽ вниз с минимумом 100 ₽ и возможность повышения при добавлении Stars. Покажите итоговую сумму до оплаты.

Smerch · СБП: отдельный метод

Создание: POST /api/merchant/v1/smerch/payments, заголовки Authorization: Bearer … и Idempotency-Key. Сумма amount_rub — целое число от 10 до 299. Обязательно укажите external_id и стабильный ID плательщика metadata.userId. Для этого метода Smerch отклоняет запрос без ID. Поля description и собственный callback_url необязательны.

{"external_id":"order-42","amount_rub":100,"metadata":{"userId":"customer-42"}}

Для явного выбора Smerch используйте отдельные адреса /api/merchant/v1/smerch/…. Автоматический каскад Stars продолжает работать отдельно.

Статус: GET /api/merchant/v1/smerch/payments/{id}. Список и отдельная статистика: /smerch/payments и /smerch/statistics. Параметр payment_method=smerch_sbp также выбирает Smerch в основных GET payments/statistics/balance.

Денежная валюта Smerch — RUB, поля статистики с единицей kopecks указаны в копейках; payer_amount, net_amount и fee_amount в карточке платежа — строки в рублях. Учёт Smerch не добавляет Stars и не изменяет баланс XTR. Баланс accounted_net — учтённые чистые поступления, не команда вывода.

Ссылка возвращается в payment_url после ответа провайдера. Код 202 и статусы creating/creation_unknown означают, что создание уточняется: повторяйте исходный запрос с тем же ключом, а не создавайте новый счёт. При кассе Telegram Stars metadata.userId должен содержать настоящий Telegram ID получателя в формате tg123456789.

Подтверждение приходит как подписанный стандартный webhook payment.paid, currency=RUB, payment_method=smerch_sbp. Проверяйте подпись и дедуплицируйте ID события. Возврат и чарджбэк отражаются отдельными состояниями. Возврат с сайта плательщика сам по себе не подтверждает оплату.