Merchant API fees and limits

Invoices carry a platform fee taken from what you receive; transfers and checks are bounded by amount limits. The figures below are the current settings, not contract terms — when they disagree with what you see, the app is right, and the reliable source is always your own paid invoices.

The invoice fee

The payer always pays the face amount of the invoice. The fee comes out of the merchant side: your app balance is credited the amount net of fee.

The fee is 3% of the invoice amount, and it steps down automatically with your trailing 30-day payment volume:

Two rules matter more than the number:

• The fee is resolved and locked in at payment time. A later change to the rate never touches an invoice that’s already been paid.
• Your rate can change with your volume. Higher payment volume over a trailing 30-day window can move you onto a lower tier automatically. You don’t apply for it and there’s nothing to configure.

To see exactly what was charged, read fee_asset and fee_amount off the paid invoice — from the invoice_paid webhook payload or from getInvoices. That’s the authoritative figure for your books.

Refunds don’t return the fee: what refundInvoice sends the payer comes out of your balance, and the fee is not refunded — including on a partial refund.

Subscription charges also carry a merchant-side fee; each charge reports its own figure in the charge.fee field of the subscription_charged webhook.

Transfer limits

transfer is bounded by a minimum and maximum per transfer, applied as a US-dollar-equivalent estimate at current rates rather than a per-asset figure. An amount outside this range is rejected with an explicit error, so handle amount_too_small and amount_too_big in your integration.

A transfer also fails when:

• your app balance is short in that asset,
• the recipient isn’t a user of the app — a payout to an unknown or mistyped Telegram ID errors instead of crediting a wallet nobody will open,
• the recipient’s account is blocked.

Rate limits

The money-moving methods are rate-limited per app (shared across all its tokens): createInvoice and createCheck at 60 per minute, refundInvoice and transfer at 30, transferBatch at 10. Read methods are unlimited. A well-behaved integration never notices; a retry loop will — back off on rate_limited rather than hammering.

Idempotency

transfer requires a spend_id you generate; createCheck and refundInvoice accept one. Reusing the same value replays the original result instead of moving funds a second time — so a timed-out request is safe to retry with the same spend_id, and only a genuinely new payout gets a new one.

What costs nothing

There’s no network fee anywhere in the Merchant API — invoices, transfers and checks all settle inside the app, off-chain. The platform fee on invoices is the only charge.

⚠️ Never derive the fee yourself

Don’t hardcode a percentage or reconstruct the net from the face amount. Tiers and rates change, and a stale constant silently corrupts your accounting. Read the recorded fee off the invoice every time.