Как начать работу с API

Создайте приложение в Mini App, один раз скопируйте его API-токен и начинайте вызывать API. Вся настройка находится в разделе Ещё → Merchant API.

Шаги

1. Откройте Ещё → Merchant API.
2. Введите Название приложения (например, «Мой магазин») и, при желании, Webhook URL.
3. Нажмите Создать приложение. Создание приложения означает принятие условий Merchant API — для чего API можно и нельзя использовать.
4. Сразу скопируйте API-токен. Он показывается один раз и больше никогда — приложение хранит только его хеш.
5. Отправьте первый запрос с токеном в заголовке TgPayCrypto-API-Token.

Первый вызов

Направьте клиент на базовый адрес API https://app.tgpaycrypto.com/pay/api и вызовите getMe, чтобы убедиться, что токен работает. getBalance возвращает балансы вашего приложения, getCurrencies — активы, которые можно использовать.

Методы чтения — GET. Методы, которые двигают деньги, — createInvoice, transfer, createCheck и их парные delete-методы — только POST, и это намеренно: суммам и ключам идемпотентности не место в логах доступа. Параметры можно передавать JSON-телом, в form-urlencoded или query-параметрами.

Тестовая сеть

Сначала соберите интеграцию в тестовой сети — тот же API, то же мини-приложение, монеты без стоимости:

	Основная сеть	Тестовая сеть
Бот	@tgpaycryptobot	@tgpaycrypto_testnet_bot
Базовый адрес API	https://app.tgpaycrypto.com/pay/api	https://testnet.tgpaycrypto.com/pay/api
MCP-сервер	https://app.tgpaycrypto.com/mcp	https://testnet.tgpaycrypto.com/mcp

Приложения и токены раздельные: токен тестовой сети не работает в основной, и наоборот. Чтобы получить деньги, откройте мини-приложение тестовой сети и нажмите Получить тестовые монеты на главном экране — 1 000 USDT, 1 000 GRAM и 0,01 BTC зачисляются как обычные депозиты, раз в час. Это может сделать любой аккаунт Telegram, так что ваш второй аккаунт — это покупатель, который оплачивает тестовые счета.

Что имитируется: адреса депозитов не существуют ни в одном блокчейне (ничего на них не отправляйте), а выводы завершаются мгновенно без реальной транзакции. Всё остальное — счета, возвраты, переводы, чеки, подписки, вебхуки, лимиты запросов — работает ровно как в основной сети. Когда закончите, создайте производственное приложение в @tgpaycryptobot и поменяйте базовый адрес.

Управление приложением

Карточка каждого приложения в разделе Merchant API показывает его ID и баланс и позволяет:

• Задать или изменить Webhook URL и сохранить его.
• Выбрать дополнительные webhook-события — когда Webhook URL задан, тумблеры Дополнительные webhook-события включают типы событий помимо invoice_paid (см. справочник вебхуков).
• Сузить, кому может платить API — у нового приложения Выплаты через API открыты любому пользователю; переключите на Только по списку (и добавьте получателей) или Выключены, если интеграция никому не платит, — это защита на случай утечки токена (см. режим выплат).
• Создать ограниченные токены — дополнительные API-токены в блоке Ограниченные токены, каждый только с выбранными правами (см. справочник API).
• Обновить токен — выпускает новый токен и мгновенно отзывает старый. Пригодится, если токен утёк; новый показывается один раз, как и при создании.
• Удалить — токены приложения перестают работать, но его баланс и история платежей сохраняются. Деньги при удалении никуда не исчезают.

Вебхуки

Если задан Webhook URL, приложение отправляет на него POST с подписанным JSON-телом:

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

Подпись — в заголовке TgPayCrypto-API-Signature (псевдоним для совместимости — прежнее TgCryptoPay-API-Signature и Crypto-Pay-API-Signature): HMAC-SHA256 от сырого тела с ключом SHA-256 от вашего API-токена. Проверяйте её, прежде чем доверять чему-либо в данных.

Неудачные доставки повторяются с экспоненциальной задержкой ещё долго, и update_id при повторах не меняется — дедуплицируйте по нему и делайте обработчик идемпотентным.

invoice_paid доставляется всегда. Остальные типы событий — истёкшие счета, активированные чеки, возвраты, события подписок — включаются тумблерами Дополнительные webhook-события. Полный список, состав данных и расписание повторов — в справочнике вебхуков.

⚠️ Берегите токен как приватный ключ

По нему проходят выплаты с баланса вашего приложения. Держите его на своём сервере и никогда — в мобильном приложении, фронтенд-бандле или закоммиченном конфиге. Сомневаетесь, не утёк ли он, — обновите токен: это мгновенно и бесплатно. И давайте каждому серверу только необходимое: ограниченный токен без права payouts может выставлять счета, но никогда не выведет ваш баланс.