Комиссии и лимиты Merchant API

Со счетов берётся комиссия платформы — из суммы, которую получаете вы; переводы и чеки ограничены по сумме. Цифры ниже — текущие настройки, а не условия договора: если они расходятся с тем, что показывает приложение, верно то, что в приложении, а самый надёжный источник — ваши собственные оплаченные счета.

Комиссия со счетов

Плательщик всегда платит номинальную сумму счёта. Комиссию платит мерчант: на баланс приложения зачисляется сумма за вычетом комиссии.

Комиссия — 3% от суммы счёта и автоматически снижается с ростом оборота за скользящие 30 дней:

Два правила важнее самой цифры:

• Комиссия определяется и фиксируется в момент оплаты. Если ставка изменится позже, уже оплаченный счёт это не затронет.
• Ваша ставка может меняться вместе с оборотом. С ростом оборота за скользящие 30 дней вы автоматически переходите на уровень с меньшей комиссией. Подавать заявку не нужно, настраивать нечего.

Чтобы узнать, сколько именно было удержано, читайте fee_asset и fee_amount у оплаченного счёта — из данных вебхука invoice_paid или из getInvoices. Именно на эту цифру опирайтесь в бухгалтерии.

При возврате комиссия не возвращается: сумма, которую refundInvoice отправляет плательщику, списывается с вашего баланса, а комиссия остаётся у платформы — при частичном возврате тоже.

Со списаний по подпискам комиссия берётся так же; её размер по каждому списанию приходит в поле charge.fee вебхука subscription_charged.

Лимиты переводов

transfer ограничен минимумом и максимумом на перевод; оба считаются в долларовом эквиваленте по текущим курсам, а не отдельно по каждому активу. Сумма вне этого диапазона отклоняется с понятной ошибкой — обрабатывайте amount_too_small и amount_too_big в своей интеграции.

Перевод также не проходит, когда:

• на балансе приложения не хватает этого актива,
• получатель не является пользователем приложения — выплата на неизвестный или ошибочный Telegram ID завершится ошибкой, а не зачислит средства в кошелёк, который никто не откроет,
• аккаунт получателя заблокирован.

Ограничение частоты запросов

Методы, которые двигают деньги, ограничены по частоте на уровне приложения (лимит общий для всех его токенов): createInvoice и createCheck — 60 в минуту, refundInvoice и transfer — 30, transferBatch — 10. Методы чтения не ограничены. Аккуратная интеграция в этот лимит не упирается, а вот цикл повторов — да: получив rate_limited, увеличивайте паузу между попытками, а не шлите запросы подряд.

Идемпотентность

Для transfer spend_id обязателен — его генерируете вы; createCheck и refundInvoice принимают его по желанию. Повторный запрос с тем же значением вернёт исходный результат, а не спишет средства второй раз, поэтому запрос, упавший по таймауту, можно спокойно повторить с тем же spend_id. Новый spend_id нужен только для действительно новой выплаты.

Что не стоит ничего

В Merchant API нигде нет комиссии сети: счета, переводы и чеки исполняются внутри приложения, а не в блокчейне. Единственный сбор — комиссия платформы со счетов.

⚠️ Никогда не вычисляйте комиссию сами

Не зашивайте процент в код и не вычисляйте чистую сумму из номинала. Уровни и ставки меняются, и устаревшая константа незаметно портит ваш учёт. Каждый раз берите комиссию из данных самого счёта.