Криптоплатежи в Telegram-боте: инвойсы, вебхуки, выплаты
Merchant API — платёжный API TG Crypto Pay для ботов и сервисов. Создайте приложение в боте, получите токен, выставляйте инвойсы из кода и получайте подписанный вебхук в момент оплаты. Или дайте адрес MCP-сервера своему ИИ-агенту — он сделает интеграцию сам. Платежи проходят внутри кошелька: без комиссии сети и без ожидания подтверждений.
База API — app.tgpaycrypto.com/pay/api · тестовая сеть — testnet.tgpaycrypto.com
От токена до первого платежа — четыре шага
Тот же сценарий, что у любого платёжного API: создать счёт, показать ссылку, дождаться события.
Создайте приложение
В боте откройте Ещё → Merchant API, укажите имя и адрес вебхука. Токен показывается один раз — храните его на сервере.
Создайте инвойс
Один POST-запрос createInvoice: сумма в крипте или в фиате, описание, срок оплаты. В ответе — ссылка на оплату.
Покажите ссылку пользователю
Кнопка или ссылка в вашем боте: пользователь оплачивает с баланса кошелька в одно касание.
Обработайте вебхук
На ваш сервер приходит invoice_paid с подписью HMAC-SHA256. Проверьте подпись, отбросьте дубли по update_id и выдайте товар.
Интеграцию может сделать ваш ИИ-агент
У Merchant API есть MCP-сервер. Дайте агенту один адрес — он прочитает документацию, создаст приложение, настроит вебхук и напишет код. Терминал и ручное копирование токена не нужны.
- Шаг 1
Отправьте агенту промпт
Любой чат с агентом: Claude Code, claude.ai, Claude Desktop, ChatGPT или другой MCP-клиент. Тот же промпт лежит в приложении: Ещё → Merchant API → Подключить ИИ-агента.
- Шаг 2
Подтвердите приложение в Telegram
Агент пришлёт ссылку t.me — бот покажет, что запрашивается, вы нажмёте одну кнопку. Ссылка работает один раз; пока вы не подтвердили, ничего не создаётся.
- Шаг 3
Агент завершит настройку сам
Он получит ограниченный токен и доделает интеграцию: инвойсы, планы подписок, вебхук. Ключ для подписи вебхуков остаётся у вас в приложении.
Токен агента может принимать платежи и настраивать вебхук, но не может переводить, выпускать чеки и делать возвраты. Вывод средств остаётся только за вами — с полным токеном в приложении.
Подробнее об агентном подключении — в документацииConnect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay Merchant API.
claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
Настройки → Коннекторы → Добавить свой коннектор → вставьте адрес app.tgpaycrypto.com/mcp
https://testnet.tgpaycrypto.com/mcp
Комиссии и лимиты
Значения берутся из открытого каталога лимитов приложения на момент сборки страницы; актуальные — в самом приложении.
Что умеет Merchant API
Приложение держит собственный баланс, отдельный от вашего кошелька: инвойсы его пополняют, выплаты и чеки тратят.
Инвойсы и возвраты
Фиксированная сумма в крипте, цена в фиате или свободная сумма на выбор плательщика. Возврат — целиком или частично, в том числе анонимному плательщику.
Подписки
Пользователь подтверждает план один раз, дальше списания идут автоматически каждый период — с событиями о каждом списании.
Переводы и чеки
Выплаты пользователям Telegram с баланса приложения и чеки — ссылки, которые может активировать кто угодно.
Вебхуки
invoice_paid приходит всегда; истечение инвойса, активация чека, возврат и события подписок включаются по желанию в настройках приложения.
Тестовая сеть
Тот же API и то же мини-приложение в @tgpaycrypto_testnet_bot. Тестовые монеты выдаются кнопкой на главной раз в час.
ИИ-агент и MCP
Дайте агенту адрес app.tgpaycrypto.com/mcp — он создаст приложение, настроит вебхук и напишет интеграцию. Вы подтверждаете создание одной кнопкой в боте.
Совместимость с Crypto Bot API
Те же имена методов, формат ответа {ok, result} и схема подписи вебхуков. Смените базовый адрес и токен — код остаётся.
Токен под контролем
Ограниченные токены по областям доступа, мгновенная ротация, режим выплат «только списку» или «выключено» и дневной лимит выплат на случай утечки.
Частые вопросы об API
Коротко о токенах, подписи вебхуков, тестировании и переезде с другого API.
Создание приложения может потребовать пройти верификацию личности — это зависит от текущей политики. Если создание завершилось ошибкой верификации, пройдите её в приложении и повторите.
Заголовок TgPayCrypto-API-Signature содержит HMAC-SHA256 от тела запроса с ключом SHA-256 от вашего основного токена. Сравнивайте подпись по сырым байтам тела; пока проверка не пройдена, не отгружайте товар и не отмечайте счёт оплаченным.
Да. Merchant API повторяет методы, формат ответа {ok, result}, строковые суммы и схему подписи Crypto Bot API. Достаточно сменить базовый адрес и токен; заголовок Crypto-Pay-API-Token принимается как псевдоним.
В тестовой сети тот же API и то же мини-приложение: бот @tgpaycrypto_testnet_bot, база testnet.tgpaycrypto.com/pay/api. Кнопка «Получить тестовые монеты» на главной выдаёт 1 000 USDT, 1 000 GRAM и 0,01 BTC раз в час. Токены основной и тестовой сети не взаимозаменяемы.
Агент получает ограниченный токен: создаёт инвойсы и планы подписок, читает баланс и статистику, настраивает адрес вебхука. Переводы, чеки и возвраты — только с полным токеном, который остаётся у вас.
Открытая документация Merchant API
Справочник методов, OpenAPI-описание и пошаговые руководства на docs.tgpaycrypto.com.
Подключите приём платежей за вечер
Создайте приложение в @tgpaycryptobot — или дайте своему ИИ-агенту ссылку на MCP-сервер и подтвердите приложение одной кнопкой.
Открыть бота