Что такое Merchant API
Merchant API — это платёжный API приложения для бизнеса и ботов. Вы создаёте приложение, получаете API-токен и с его помощью выставляете счета пользователям Telegram, отправляете им выплаты и проверяете баланс — всё из собственного кода.
Это тот же продукт, но со стороны разработчика: счёт, созданный через API, — тот самый счёт, который пользователь оплачивает со своего баланса после подтверждения оплаты.
Что с ним можно делать
- Счета — создайте запрос на оплату (фиксированная сумма в криптовалюте, цена в фиате или свободная сумма, которую выбирает плательщик), отправьте плательщику ссылку и получайте подписанный вебхук после оплаты, если настроен Webhook URL.
- Возвраты — верните сумму оплаченного счёта, целиком или частично, тому, кто платил, — включая анонимных плательщиков.
- Переводы — отправляйте криптовалюту с баланса приложения пользователю Telegram: по одному или до 100 за один вызов.
- Чеки — выпускайте с баланса приложения ссылки для любого получателя или для указанных пользователей с учётом настроек выплат.
- Подписки — регулярные платежи: пользователь один раз подтверждает план, и дальше списания идут автоматически каждый расчётный период.
- Балансы, валюты, курсы обмена и статистика — методы только для чтения, для вашего собственного учёта.
Как всё устроено
- Ваше приложение держит баланс, отдельный от вашего личного кошелька.
- Счета, оплаченные пользователями, зачисляются на баланс приложения.
- Переводы и чеки списывают с него средства.
- Поддерживаемые события платежей могут приходить на ваш сервер подписанным вебхуком, если настроены URL и подписка на нужные события.
Платежи исполняются внутри приложения, а не в блокчейне: без комиссии сети,
без ожидания подтверждений, а средства можно использовать сразу после
поступления. При этом плательщик может оплатить счёт из внешнего кошелька:
если этот способ доступен, депозит зачисляется в его собственный
кошелёк. Для автоматической оплаты также нужны достаточный баланс,
отсутствие ограничений на исходящие платежи и действующий срок оплаты.
Перед выполнением заказа убедитесь, что счёт имеет статус paid.
Совместимость с Crypto Bot
API намеренно повторяет Crypto Bot: те же имена методов, та же обёртка ответа
{ok, result}, те же суммы десятичными строками, та же схема подписи
вебхуков. Чтобы адаптировать существующую интеграцию, замените базовый
URL и токен, затем проверьте используемые методы по нашему справочнику. Как и у
Crypto Bot, у нас есть тестовая сеть с
отдельным ботом и базовым адресом.
Канонический заголовок токена — TgPayCrypto-API-Token;
прежнее имя TgCryptoPay-API-Token (до 2026-09-07) и Crypto-Pay-API-Token принимаются как псевдонимы, чтобы существующие
клиентские библиотеки продолжали работать без изменений.
⚠️ API-токен открывает доступ к средствам приложения
Основной токен позволяет выплачивать средства с учётом режима и лимитов приложения. Держите токен на сервере, вне клиентских приложений и репозиториев, и обновите его, как только заподозрите утечку. Серверам, которым не нужен полный доступ, выпустите ограниченный токен только с теми правами, которые они действительно используют, — см. справочник API.
Дальше
Была ли статья полезной?
Спасибо за отзыв.