What is the Merchant API?
The Merchant API is the app’s payment API for businesses and bots. You create an app, get an API token, and use it to bill Telegram users, send them payouts, and check your balance — all from your own code.
It’s the developer side of the same product users see: an invoice you create through the API is the invoice they pay from their balance with one tap.
What you can do with it
- Invoices — create a payment request (a fixed crypto amount, a fiat-priced one, or an open amount the payer chooses), send the payer its link, and get a signed callback the moment it’s paid.
- Refunds — return a paid invoice’s amount, in full or in part, to whoever paid it — anonymous payers included.
- Transfers — send crypto from your app balance to a Telegram user, one at a time or up to 100 in a batch.
- Checks — issue redeemable links anyone can claim, from your app balance.
- Subscriptions — recurring billing: users approve a plan once and are charged automatically every period.
- Balances, currencies, exchange rates and stats — read-only endpoints for your own bookkeeping.
How it fits together
- Your app holds a balance, separate from your personal wallet.
- Invoices paid by users credit that app balance.
- Transfers and checks spend from it.
- Every event that matters can be pushed to your server as a signed webhook.
Payments settle inside the app, not on-chain: no network fee, no confirmations to wait for, and the funds are usable the instant they land. A payer can still fund an invoice from an external wallet — their deposit lands in their own wallet and the invoice settles from it automatically; on your side it looks exactly like any other paid invoice.
Compatible with Crypto Bot
The API deliberately mirrors Crypto Bot’s: same method names, same
{ok, result} envelope, same decimal-string amounts, same webhook signature
scheme. You can point an existing Crypto Bot integration at us by changing the
base URL and the token — the request and response shapes don’t change. Like
Crypto Bot, we run a testnet with a
separate bot and base URL.
The canonical token header is TgPayCrypto-API-Token; the pre-2026-09-07
TgCryptoPay-API-Token still works, and Crypto-Pay-API-Token
is accepted as an alias so existing client libraries keep working unmodified.
⚠️ Your API token is a spending key
Anyone holding it can transfer your app’s balance out. Keep it server-side, out of client apps and repositories, and rotate it the moment you suspect it leaked. For servers that don’t need full access, mint a restricted token limited to the scopes they actually use — see the API reference.
Next
Was this article helpful?
Thanks for the feedback.