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

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

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

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

Комиссия — 1,5% от суммы счёта. Ставка одна для всех счетов, скидок за оборот нет.

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

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

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

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

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

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

Для transfer установлен максимум на перевод — $25 000 в долларовом эквиваленте, а не отдельная сумма для каждого актива. Может быть задан и минимум на перевод, но сейчас его нет. Если перевод отклонён из-за этих лимитов, API возвращает amount_too_big (или amount_too_small, если минимум появится; обе — 400) — обрабатывайте эти ошибки в своей интеграции. К активу, у которого сейчас нет курса к доллару, максимум не применяется.

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

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

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

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

Владелец может задать лимит за последние 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 нигде нет комиссии сети: счета, переводы и чеки исполняются внутри приложения, а не в блокчейне. Комиссия платформы может взиматься со счетов и списаний по подпискам. При автоматическом обмене применяется котировка обмена. За отправку средств из внешнего кошелька комиссию может взимать этот кошелёк или сеть.

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

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