Merchant API (Developers)
The merchant API: apps, invoices, transfers, and webhooks.
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.
Getting started as a developer
Create an app in the Mini App, copy its API token once, and start calling the API. The whole setup lives under More → Merchant API.
Connect an AI agent
Connect an AI coding agent that supports remote MCP servers to https://app.tgpaycrypto.com/mcp. It can read the API docs, request a merchant app, configure webhooks and help write your integration. You approve app creation in the bot; the agent receives a restricted token without you copying it by hand. Review and test the resulting integration before accepting real payments.
Accepting payments with invoices
An invoice is how you charge a Telegram user. You create one through the API, send the payer its link, and a successful payment credits your app balance minus the merchant fee.
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.
Merchant API reference
The conventions every method shares, plus the read-only catalog methods. Method-by-method pages: invoices and refunds, transfers and checks, subscriptions, webhooks.
API reference: invoices and refunds
The invoice methods: createInvoice, getInvoices, deleteInvoice, refundInvoice. Conventions (auth, envelope, amounts, spend_id) are on the Merchant API reference page; the guided walkthrough is Accepting payments with invoices.
API reference: transfers and checks
The payout methods. A transfer sends funds from your app balance to a Telegram user's wallet, or holds them until a new recipient joins; a check is a claimable link you fund up front. Conventions (auth, envelope, amounts, spend_id) are on the Merchant API reference page.
API reference: subscriptions
Recurring billing — an extension over Crypto Bot. You create a plan (amount + period), send users its approval link, and the platform charges them from their wallet balance every period, crediting your app balance net of fee. Conventions are on the Merchant API reference page.
API reference: webhooks
Webhooks push events to your server after they happen. Set the Webhook URL (optional) on your app in More → Merchant API; the platform then POSTs a signed JSON body for every event you're subscribed to.
Merchant API terms
These terms govern the Merchant API — apps, API tokens, invoices, subscriptions, transfers, checks, webhooks and the AI-agent connector. They apply in addition to the app's general terms of use and its AML policy. By creating an app you accept them; by continuing to use an app created before 7 September 2026 you accept them too.