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

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

Шаги

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

Первый вызов

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

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

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

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

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

Вебхуки

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

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

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

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

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

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

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