Криптоплатежі в Telegram-боті: рахунки, вебхуки, виплати
Мерчант API — платіжний API TG Crypto Pay для ботів і сервісів. Створіть застосунок у боті, отримайте токен, виставляйте рахунки з коду й отримуйте підписаний вебхук одразу після оплати. Або передайте URL MCP-сервера ШІ-агенту — він виконає інтеграцію. Платежі проходять усередині гаманця без комісії мережі й очікування підтверджень.
Базова адреса API — app.tgpaycrypto.com/pay/api · тестова мережа — testnet.tgpaycrypto.com
Від токена до першої оплати за чотири кроки
Звичний сценарій платіжного API: створити рахунок, показати посилання, дочекатися події.
Створіть застосунок
У боті відкрийте «Ще» → «Мерчант API», введіть назву й URL вебхука. Токен показується лише раз — збережіть його на своєму сервері.
Створіть рахунок
Один POST-запит createInvoice: сума в криптовалюті чи фіаті, опис і термін оплати. У відповіді — посилання для оплати.
Покажіть посилання користувачу
Кнопка чи посилання у вашому боті: користувач платить з балансу гаманця одним натисканням.
Обробіть вебхук
Ваш сервер отримує invoice_paid із підписом HMAC-SHA256. Перевірте підпис, відсійте дублікати за update_id та видайте товар.
Ваш ШІ-агент може виконати інтеграцію
Мерчант API має MCP-сервер. Передайте агенту одну адресу — він прочитає документацію, створить застосунок, налаштує вебхук і напише код. Без термінала й ручного копіювання токена.
- Крок 1
Надішліть запит агенту
Будь-який чат з агентом: Claude Code, claude.ai, Claude Desktop, ChatGPT або інший MCP-клієнт. Той самий запит є в застосунку: «Ще» → «Мерчант 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
Комісії та ліміти
Значення взято з відкритого каталогу лімітів застосунку на момент створення цієї сторінки. Актуальні умови — у застосунку.
Що вміє Мерчант API
Застосунок має власний баланс, окремий від вашого гаманця: оплата рахунків його поповнює, виплати й чеки — витрачають.
Рахунки й повернення
Фіксована сума в криптовалюті, ціна у фіаті або довільна сума на вибір платника. Повне чи часткове повернення, зокрема анонімним платникам.
Підписки
Користувач підтверджує план один раз. Далі оплата списується автоматично за кожен період; кожне списання супроводжується подією.
Перекази й чеки
Виплати користувачам Telegram із балансу застосунку та чеки — посилання, за якими можна отримати кошти.
Вебхуки
invoice_paid надсилається завжди. Події завершення терміну рахунку, активації чека, повернення та підписок вмикаються окремо для кожного застосунку.
Тестова мережа
Той самий API і Mini App у @tgpaycrypto_testnet_bot. Тестові монети можна отримати кнопкою на головному екрані раз на годину.
ШІ-агент і MCP
Передайте агенту app.tgpaycrypto.com/mcp — він створить застосунок, налаштує вебхук і напише інтеграцію. Ви підтвердите створення однією кнопкою в боті.
Сумісність із Crypto Bot API
Ті самі назви методів, формат відповіді {ok, result} і схема підпису вебхуків. Змініть базову адресу й токен — код залишиться.
Контроль токена
Токени з обмеженими правами, миттєва ротація, режим виплат лише користувачам зі списку або повна заборона виплат, а також денний ліміт на випадок витоку токена.
Запитання про API
Про токени, підписи вебхуків, тестування та перехід з іншого API.
Залежно від поточних правил створення застосунку може вимагати завершеної верифікації. Якщо з’явилася відповідна помилка, пройдіть верифікацію в застосунку та спробуйте знову.
Заголовок TgPayCrypto-API-Signature містить HMAC-SHA256 тіла запиту з ключем SHA-256 від вашого основного токена. Перевіряйте підпис за початковими байтами тіла. До успішної перевірки не видавайте товар і не позначайте рахунок оплаченим.
Так. Мерчант API повторює методи Crypto Bot API, формат {ok, result}, суми десятковими рядками та схему підпису. Змініть базову адресу й токен; заголовок Crypto-Pay-API-Token приймається як альтернативний.
У тестовій мережі — той самий API і Mini App: бот @tgpaycrypto_testnet_bot, базова адреса testnet.tgpaycrypto.com/pay/api. Кнопка отримання тестових монет на головному екрані видає 1 000 USDT, 1 000 GRAM і 0,01 BTC раз на годину. Токени основної й тестової мереж не взаємозамінні.
Агент отримує токен з обмеженими правами: створює рахунки й плани підписок, читає баланс і статистику, задає URL вебхука. Для переказів, чеків і повернень потрібен повний токен, який залишається у вас.
Відкрита документація Мерчант API
Довідник методів, опис OpenAPI та покрокові інструкції на docs.tgpaycrypto.com.
Підключіть платежі за вечір
Створіть застосунок у @tgpaycryptobot або передайте ШІ-агенту посилання на MCP-сервер і підтвердьте створення однією кнопкою.
Відкрити бота