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.

Steps

1. Open More → Merchant API.
2. Enter an App name (e.g. “My Store”) and, optionally, a Webhook URL.
3. Tap Create app. Creating an app accepts the Merchant API terms — what you may and may not use the API for.
4. Copy the API token immediately. It’s shown once and never again — the app stores only a hash of it.
5. Send your first request with the token in the TgPayCrypto-API-Token header.

Your first call

Point your client at the API base https://app.tgpaycrypto.com/pay/api and call getMe to confirm the token works. getBalance returns your app’s balances, getCurrencies the assets you can use.

Read methods are GET. The methods that move money — createInvoice, transfer, createCheck and their delete counterparts — are POST only, on purpose: amounts and idempotency keys don’t belong in access logs. Parameters may be sent as a JSON body, form-urlencoded, or query params.

Testnet

Build against the test network first — same API, same Mini App, coins with no value:

	Mainnet	Testnet
Bot	@tgpaycryptobot	@tgpaycrypto_testnet_bot
API base	https://app.tgpaycrypto.com/pay/api	https://testnet.tgpaycrypto.com/pay/api
MCP server	https://app.tgpaycrypto.com/mcp	https://testnet.tgpaycrypto.com/mcp

Apps and tokens are separate: a testnet token does not work on mainnet, and vice versa. To get money, open the testnet Mini App and tap Get test coins on the home screen — 1 000 USDT, 1 000 GRAM and 0.01 BTC land as ordinary deposits, once an hour. Any Telegram account can do this, so a second account of yours is the customer who pays your test invoices.

What is simulated: deposit addresses exist on no blockchain (send nothing to them) and withdrawals complete instantly without a real transaction. Everything else — invoices, refunds, transfers, checks, subscriptions, webhooks, rate limits — behaves exactly as on mainnet. When you’re done, create a production app in @tgpaycryptobot and switch the base URL.

Managing an app

Each app card in Merchant API shows its app ID and balance, and lets you:

• Set or change the webhook URL and save it.
• Pick extra webhook events — once a webhook URL is set, the Extra webhook events toggles let you opt into event types beyond invoice_paid (see the webhooks reference).
• Narrow who the API may pay — Payouts through the API is Any user for a new app; switch it to Listed users only (and list the recipients) or Off if your integration never pays people — a fence in case the token leaks (see payout mode).
• Create restricted tokens — extra API tokens under Restricted tokens, each limited to the scopes you pick (see the API reference).
• Rotate token — issues a new token and instantly invalidates the old one. Use this if a token leaked; the new one is shown once, same as at creation.
• Delete — the app stops authenticating, but its balance and payment history are preserved. Deleting an app never makes its money disappear.

Webhooks

If you set a webhook URL, the app POSTs a signed JSON body to it:

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

The signature is in the TgPayCrypto-API-Signature header (with TgCryptoPay-API-Signature and Crypto-Pay-API-Signature as compat aliases): HMAC-SHA256 over the raw body, keyed by the SHA-256 of your API token. Verify it before trusting anything in the payload.

Deliveries are retried with exponential backoff over an extended period, and update_id stays the same across retries — key your deduplication on it and make your handler idempotent.

invoice_paid is always delivered. Other event types — expired invoices, claimed checks, refunds, subscription events — are opt-in via the Extra webhook events toggles. The full list, payload shapes, and the retry schedule are in the webhooks reference.

⚠️ Guard the token like a private key

It authorizes payouts from your app balance. Keep it on your server, never in a mobile app, front-end bundle or committed config. If you’re unsure whether it leaked, rotate it — rotation is instant and costs nothing. And give each server only what it needs: a restricted token without the payouts scope can create invoices but can never move your balance out.