Merchant API

Crypto payments in a Telegram bot: invoices, webhooks, payouts

The Merchant API is TG Crypto Pay's payment API for bots and services. Create an app in the bot, get a token, issue invoices from your code and receive a signed webhook the moment one is paid. Or hand the MCP server URL to your AI agent and let it do the integration. Payments settle inside the wallet: no network fee and no waiting for confirmations.

Get a token API documentation Via an AI agent
API base — app.tgpaycrypto.com/pay/api · testnet — testnet.tgpaycrypto.com
The Merchant API screen: app, token and webhook events
Webhook delivered
Testnet
How it works

From token to first payment in four steps

The same flow as any payment API: create an invoice, show the link, wait for the event.

Step 1

Create an app

In the bot open More → Merchant API, enter a name and a webhook URL. The token is shown once — keep it on your server.

Step 2

Create an invoice

One POST request, createInvoice: an amount in crypto or fiat, a description, a deadline. The response carries the payment link.

Step 3

Show the link to the user

A button or a link in your bot: the user pays from the wallet balance with one tap.

Step 4

Handle the webhook

Your server receives invoice_paid signed with HMAC-SHA256. Verify the signature, dedupe on update_id and deliver the goods.

AI agent

Your AI agent can do the integration

The Merchant API has an MCP server. Give your agent one URL — it reads the docs, creates the app, sets up the webhook and writes the code. No terminal, no token to copy by hand.

  1. Step 1

    Send the prompt to your agent

    Any agent chat: Claude Code, claude.ai, Claude Desktop, ChatGPT or another MCP client. The same prompt is in the app: More → Merchant API → Connect an AI agent.

  2. Step 2

    Approve the app in Telegram

    The agent gives you a t.me link — the bot shows what is being requested, you tap one button. The link works once; nothing is created until you approve.

  3. Step 3

    The agent finishes the setup itself

    It receives a restricted token and completes the integration: invoices, subscription plans, the webhook. The webhook signing key stays with you in the app.

The agent's token can accept payments and configure the webhook, but it cannot transfer, issue checks or refund. Moving funds out stays with you — with the full token in the app.

More about the agent flow — in the documentation
Prompt for any agent
Connect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay Merchant API.
Claude Code
claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
claude.ai, Claude Desktop, ChatGPT

Settings → Connectors → Add custom connector → paste app.tgpaycrypto.com/mcp

Testnet
https://testnet.tgpaycrypto.com/mcp
Terms

Fees and limits

Values come from the app's public limits catalog at the time this page was built; the app itself is the live source.

Invoice feePaid by the merchant: the app balance is credited net of the fee. The rate is locked at payment time and never changes for invoices already paid.
3%
Volume discountThe rate steps down automatically with your trailing 30-day volume: from $10,000 — 2.9%, from $25,000 — 2.8%, from $50,000 — 2.7%, from $75,000 — 2.6%, from $100,000 — 2.5%.
down to 2.5%
Network feeInvoices, transfers and checks settle inside the wallet, not on-chain: no confirmations to wait for, funds usable at once.
0
Payouts to usersThe transfer method sends crypto from the app balance to a Telegram user by ID; transferBatch pays up to 100 recipients in one call. A retry with the same spend_id never charges twice.
up to $25,000
Rate limitscreateInvoice and createCheck at 60 per minute, transfer and refundInvoice at 30, transferBatch at 10. Read methods are unlimited.
60 per minute
Webhook deliveryA 2xx within 10 seconds counts as delivered; otherwise retries with exponential backoff over about three days. update_id stays the same across retries.
up to 17 attempts
What you get

What the Merchant API does

An app holds its own balance, separate from your wallet: invoices credit it, payouts and checks spend from it.

Invoices and refunds

A fixed crypto amount, a fiat-priced one or an open amount the payer chooses. Refunds in full or in part, anonymous payers included.

Subscriptions

The user approves a plan once; after that every period is charged automatically, with an event for each charge.

Transfers and checks

Payouts to Telegram users from the app balance, and checks — links anyone can claim.

Webhooks

invoice_paid is always sent; invoice expiry, check claims, refunds and subscription events are opt-in per app.

Testnet

The same API and the same Mini App in @tgpaycrypto_testnet_bot. Test coins come from a button on the home screen, once an hour.

AI agent and MCP

Give your agent app.tgpaycrypto.com/mcp — it creates the app, sets the webhook and writes the integration. You approve the app with one button in the bot.

Crypto Bot API compatible

The same method names, {ok, result} envelope and webhook signature scheme. Change the base URL and the token — the code stays.

Token under control

Scoped restricted tokens, instant rotation, a payout mode of “listed users only” or “off”, and a daily payout cap in case a token leaks.

FAQ

API questions

Tokens, webhook signatures, testing and migrating from another API, in short.

Creating an app may require completed identity verification, depending on the current policy. If creation fails with a verification error, finish verification in the app and try again.

The TgPayCrypto-API-Signature header carries the HMAC-SHA256 of the request body keyed by the SHA-256 of your main token. Compare it over the raw body bytes; until the check passes, do not ship anything or mark the invoice paid.

Yes. The Merchant API mirrors the Crypto Bot API's methods, {ok, result} envelope, decimal-string amounts and signature scheme. Change the base URL and the token; the Crypto-Pay-API-Token header is accepted as an alias.

The testnet runs the same API and the same Mini App: the bot is @tgpaycrypto_testnet_bot, the base is testnet.tgpaycrypto.com/pay/api. The “Get test coins” button on the home screen gives 1,000 USDT, 1,000 GRAM and 0.01 BTC once an hour. Mainnet and testnet tokens are not interchangeable.

The agent gets a restricted token: it creates invoices and subscription plans, reads the balance and stats, and sets the webhook URL. Transfers, checks and refunds need the full token, which stays with you.

Every method — in the documentationQuestions — @tgpayhelpbot
Documentation

Public Merchant API documentation

The method reference, the OpenAPI description and step-by-step guides at docs.tgpaycrypto.com.

Wire up payments in an evening

Create an app in @tgpaycryptobot — or hand your AI agent the MCP server link and approve the app with one button.

Open the bot