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

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

Шаги

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

Первый вызов

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

Методы чтения — GET. Методы записи, например createInvoice, transfer, createCheck, deleteInvoice и deleteCheck, — только POST. Параметры можно передавать JSON-телом, в form-urlencoded или query-параметрами. Лучше передавать их в теле запроса, чтобы суммы и ключи идемпотентности не попадали в логи URL.

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

Сначала соберите интеграцию в тестовой сети — тот же 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

Приложения и токены раздельные: токен тестовой сети не работает в основной, и наоборот. Чтобы получить тестовую криптовалюту, откройте мини-приложение тестовой сети и нажмите Получить тестовую криптовалюту на главном экране. Тестовый набор зачисляется как обычные депозиты; активы в отключённых сетях пропускаются. Приложение покажет, что зачислено и когда можно повторить запрос. Второй аккаунт Telegram можно использовать как покупателя для оплаты тестовых счетов.

Депозиты и выводы имитируются без реальных транзакций в блокчейне. Никогда не отправляйте настоящие средства на депозитный адрес тестовой сети. Контракт API общий, но доступные функции, курсы и лимиты могут отличаться от основной сети. Когда закончите, создайте приложение для работы с реальными средствами в @tgpaycryptobot и поменяйте базовый адрес.

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

Откройте приложение в разделе Merchant API, чтобы увидеть его ID и баланс. Здесь можно:

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

Вебхуки

Если задан 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 при повторах не меняется — дедуплицируйте по нему и делайте обработчик идемпотентным.

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

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

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