RU

Приём криптоплатежей в Telegram-боте: счёт из бота, оплата в чате и вебхуки

7 мин чтения

Приём криптоплатежей в Telegram-боте: счёт из бота, оплата в чате и вебхуки

Эта инструкция — для тех, кто продаёт через Telegram-бота: подписки, доступ к закрытому каналу, цифровые товары, пополнение баланса в сервисе. Покупатель уже в чате, и платить ему удобнее там же. Задача — чтобы бот сам создавал счёт, сам узнавал об оплате и сам выдавал товар, без ручной сверки переводов.

SnapEX Pay не требует KYC ни от вас, ни от ваших покупателей и не ограничивает страны. Свой кошелёк и нода блокчейна боту не нужны: деньги приходят на баланс мерчанта в USDT. Что нельзя продавать через SnapEX Pay — в правилах для мерчантов.

  • 1%комиссия с платежа, без абонентской платы — из вашей суммы или сверху для покупателя
  • 1запрос к API — и у бота есть ссылка на оплату или адрес с точной суммой
  • ~10 сподтверждается тестовый счёт: проверка бота без реальных денег

Как проходит оплата в боте

От кнопки «Купить» до выдачи товара

Покупательжмёт кнопку тарифа в боте
Ботсоздаёт счёт через API
ОплатаUSDT или другая монета
Вебхукinvoice.paid с подписью
Товарбот присылает доступ в чат

Бот общается с Telegram как обычно — через long polling или свой вебхук Telegram. С SnapEX Pay его связывают два канала: запросы бота к API (создать и перечитать счёт) и вебхуки SnapEX Pay на ваш HTTPS-адрес.

Шаг 1. Заведите аккаунт мерчанта и API-ключ

  • Зарегистрируйтесь на pay.snapex.pro. Аккаунт обменника snapex.pro подходит — это один аккаунт. Документы не нужны.
  • В кабинете откройте «Разработчикам» и выпустите API-ключ. Он показывается один раз — сразу сохраните его в настройках бота. Боту нужны права invoices.read и invoices.write.
  • Укажите адрес вебхука — HTTPS-адрес вашего сервера, где бот принимает уведомления. Секрет подписи whsec_… тоже показывается один раз.

Шаг 2. Создавайте счёт по нажатию кнопки

На каждое нажатие тарифа бот отправляет POST /api/v1/merchant/invoices. Что важно передать:

  • Сумму — amount_usd, или цену в своей валюте: price_amount и price_currency (например, RUB или EUR) — SnapEX Pay сам пересчитает её в USD по курсу на момент создания счёта.
  • Номер заказа — external_id: по нему бот потом найдёт, кому выдать товар. Он должен быть уникальным, поэтому кладите туда id заказа из базы бота, а не Telegram ID покупателя.
  • Заголовок Idempotency-Key — обязателен. Покупатель нажал кнопку дважды или сеть оборвалась — повтор с тем же ключом вернёт тот же счёт, а не создаст второй.
  • Срок — expires_in в секундах, от 1 минуты до 24 часов; по умолчанию 30 минут.
  • Кто платит 1% — fee_on: merchant (из вашей суммы) или customer (сверху для покупателя).

Шаг 3. Покажите оплату: ссылкой или прямо в чате

Два способа показать счёт в боте

Кнопка со ссылкойпроще всего
  1. Счётсоздан без монеты
  2. Кнопка«Оплатить» со ссылкой на страницу оплаты
  3. Страница оплатыпокупатель сам выбирает монету и сеть
  4. Статусстраница обновляется сама
Оплата в чатебез перехода из Telegram
  1. Монетыбот показывает их кнопками из ответа API
  2. Выбормонета передаётся в API
  3. Сообщениеадрес и точная сумма из ответа API
  4. Ответбот пишет «оплачено» по вебхуку
  • Ссылка. В ответе API есть pay_url — поставьте его в кнопку под сообщением. На странице SnapEX Pay покупатель выбирает одну из 70+ монет, видит адрес, QR-код и сумму, а статус обновляется без перезагрузки.
  • Прямо в чате. В ответе на создание счёта есть список methods — монеты и сети, доступные для этой суммы. Бот показывает их кнопками, а выбор покупателя отправляет в POST /api/v1/merchant/invoices/{id}/methods с asset_id. В ответе — payment.address и payment.amount: бот присылает их сообщением, и покупатель копирует адрес в кошелёк, не выходя из Telegram. Если монета известна заранее, передайте asset_id сразу при создании счёта — адрес придёт в первом же ответе.

Показывайте сумму ровно как в payment.amount и напомните, что биржа может вычесть свою комиссию из перевода: меньшая сумма — это недоплата (шаг 4).

Шаг 4. Выдавайте товар по вебхуку

О каждом изменении счёта SnapEX Pay шлёт вебхук. Для бота главные события:

Что бот делает на каждое событие

  1. Монета выбранаinvoice.awaiting. Счёт ждёт перевод — адрес и сумма уже известны.
  2. Пришло меньшеinvoice.underpaid. Попросите доплатить остаток payment.remaining_amount на тот же адрес.
  3. Оплаченоinvoice.paid. Перечитайте счёт через API и выдайте товар.
  4. Доплаты не былоinvoice.partially_paid. Полученная часть уже на балансе — решите сами: доп. счёт на остаток или частичный заказ.

Ещё есть invoice.expired (счёт истёк неоплаченным) и invoice.extra_payment (на уже оплаченный счёт пришёл ещё платёж — он зачислен отдельно).

Как обработать уведомление надёжно:

  • Проверьте подпись. Заголовок Webhook-Signature — HMAC-SHA256 от {Webhook-Timestamp}.{сырое тело} вашим секретом whsec_…. Если перед ботом стоит прокси, он должен передавать тело без изменений.
  • Не верьте только телу. Перед выдачей перечитайте счёт GET /api/v1/merchant/invoices/{id} и проверьте, что там paid и что external_id — ваш заказ.
  • Выдавайте один раз. Не ответил сервер — SnapEX Pay повторит доставку, всего до 5 попыток. Отметьте заказ выданным в базе бота, тогда повтор ничего не сломает.

Подробнее о подписи и повторах — в гайде «Вебхуки криптоплатежей», о недоплатах — «Клиент прислал меньше суммы счёта».

Шаг 5. Проверьте бота на тестовом счёте

Создайте счёт с environment: "test" и пройдите покупку сами. На странице оплаты будет метка Test; выберите любую монету — примерно через 10 секунд оплата подтвердится сама, отправлять ничего не нужно. Убедитесь, что вебхук пришёл, подпись прошла и товар выдан один раз. Затем уберите test: пока бот создаёт тестовые счета, всё покупается без денег. Подробнее — «Как протестировать криптоплатежи без денег».

Пополнение баланса в боте: постоянный адрес

Если в боте есть внутренний баланс, выставлять счёт на каждое пополнение не обязательно. Выдайте пользователю постоянный адрес: POST /api/v1/merchant/static-addresses с монетой и customer_ref — например, Telegram ID пользователя. Повторный запрос с тем же customer_ref вернёт тот же адрес, так что его можно показывать в меню «Пополнить» хоть каждый раз.

  • Поддерживаются USDT в сетях TRC20, ERC20, BEP20 и Polygon, USDC Polygon, BTC, LTC, ETH и TRX. USDT и USDC зачисляются 1:1, остальные монеты — по курсу в USDT.
  • Пришёл перевод — вебхук static_deposit.detected, зачислен — static_deposit.credited с customer_ref: бот находит пользователя и пополняет его баланс.
  • Минимум пополнения — $0,50. Пишите сеть и монету рядом с адресом: неподдерживаемые токены автоматически не зачисляются.

Уведомления об оплатах вам в Telegram

Это не для покупателей, а для вас. В кабинете мерчанта нажмите «Подключить Telegram» — откроется @snapexpay_bot, и он будет присылать сообщение о каждом платеже на баланс: счёт оплачен полностью, частично или с доплатой, выплата выполнена. Тестовые счета приходят с пометкой «ТЕСТ». Ссылка одноразовая и действует 30 минут; отключить можно командой /stop или в кабинете.

Продаёте VPN? Есть готовый бот

Для VPN-сервисов на Marzban, 3x-ui или Remnawave писать бота не нужно: есть бесплатный бот с открытым кодом (MIT). Он показывает тарифы, создаёт счёт SnapEX Pay, проверяет вебхук и сам создаёт или продлевает пользователя в панели. Без панели он только принимает оплату, а доступ вы выдаёте сами. Установка по шагам — в гайде «Продажа VPN-подписок через Telegram-бота за USDT».

Чек-лист перед запуском

Перед тем как открыть оплату в боте

  • API-ключ с правами invoices.read и invoices.write лежит в настройках бота, не в коде.
  • Вебхук на HTTPS-адрес указан, секрет whsec_… сохранён, подпись проверяется.
  • Каждый счёт создаётся с Idempotency-Key и external_id заказа.
  • Товар выдаётся только по счёту в статусе paid, перечитанному через API, и один раз.
  • Недоплата: бот просит доплатить остаток и не выдаёт товар до paid.
  • Тестовая покупка прошла, тестовый режим выключен.
  • Комиссия: решено, кто платит 1%, — вы или покупатель.

Сколько стоит и как выводить

  • Комиссия 1% с платежа, без платы за подключение и абонентской платы.
  • Минимальный счёт — от $0,50 в USDT TRC20, ERC20, BEP20, а также LTC, ETH и TRX; остальные монеты — в счетах от $8. Хватает и на недорогие тарифы.
  • Вывод — баланс в USDT, вывод из кабинета на криптоадрес сразу, без холдов и резервов. Сервисной комиссии за вывод нет, только сетевая.

Уже принимаете оплату в боте другим способом? Отказываться не нужно: добавьте кнопку SnapEX Pay рядом — покупатель сам выберет, чем платить. Полное описание API — в документации.

Готовы принимать криптовалюту?

Создайте аккаунт мерчанта и получите API-ключ. 1% с платежа, без абонентской платы.

← Все статьи

Розыгрыш $200

Случайному участнику.

До конца 2дн 13ч 13мин 31сек Подписаться @snapex_pay