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

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

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

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

Комиссия — 3% от суммы счёта до применения скидки за оборот. Итоговая ставка зависит от действующих уровней и оборота оплаченных счетов за последние 30 дней:

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

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

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

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

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

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

Для transfer установлены минимум и максимум на перевод в долларовом эквиваленте, а не отдельная сумма для каждого актива. Если перевод отклонён из-за этих лимитов, API возвращает amount_too_small или amount_too_big — обрабатывайте эти ошибки в своей интеграции.

Для неизвестного username вместо ошибки создаётся ожидающая выплата, если режим выплат это разрешает. См. переводы и чеки.

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

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

Дневной лимит выплат

Владелец может задать лимит за последние 24 часа в настройках выплат приложения. Переводы, чеки и выплаты с баланса приложения учитываются вместе. Превышение возвращает 403 daily_cap_exceeded; пакет проверяется до первой выплаты. Возвраты в этот лимит не входят. getMe возвращает daily_payout_max_usd_cents и daily_payout_spent_usd_cents.

Ограничения аккаунта владельца также могут блокировать переводы, чеки и возвраты (403 verification_required), а временная приостановка — возвращать 503 merchant_payouts_paused.

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

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

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

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

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

В Merchant API нигде нет комиссии сети: счета, переводы и чеки исполняются внутри приложения, а не в блокчейне. Комиссия платформы может взиматься со счетов и списаний по подпискам. При автоматическом обмене применяется котировка обмена. За отправку средств из внешнего кошелька комиссию может взимать этот кошелёк или сеть.

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

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