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 after confirming payment.
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 receive a signed webhook after payment if a webhook URL is configured.
- 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 — fund claimable links from your app balance, for anyone or for named recipients, subject to your payout settings.
- 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.
- Supported payment events can be pushed to your server as a signed webhook when you configure the URL and event subscriptions.
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 when that option is available.
The deposit credits their own wallet; automatic payment also requires enough
balance, no outgoing restriction, and a valid payment deadline. On your
side, confirm the invoice is paid before fulfilling the order.
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. To adapt an existing integration, change the base URL and token,
then test the methods you use against our reference. 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
A main token authorizes payouts within the app’s payout mode and limits. 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.