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