Комісії та ліміти Мерчант 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, і лише справді нова виплата отримує новий.

Що не коштує нічого

Комісії мережі в Мерчант API немає ніде — рахунки, перекази та чеки виконуються всередині застосунку, поза блокчейном. Комісія платформи з рахунків — єдиний збір.

⚠️ Ніколи не обчислюйте комісію самі

Не зашивайте відсоток у код і не відновлюйте чисту суму з номіналу. Рівні та ставки змінюються, і застаріла константа непомітно псує ваш облік. Щоразу читайте записану комісію з рахунка.