Эта инструкция — для тех, кто продаёт через Telegram-бота: подписки, доступ к закрытому каналу, цифровые товары, пополнение баланса в сервисе. Покупатель уже в чате, и платить ему удобнее там же. Задача — чтобы бот сам создавал счёт, сам узнавал об оплате и сам выдавал товар, без ручной сверки переводов.
SnapEX Pay не требует KYC ни от вас, ни от ваших покупателей и не ограничивает страны. Свой кошелёк и нода блокчейна боту не нужны: деньги приходят на баланс мерчанта в USDT. Что нельзя продавать через SnapEX Pay — в правилах для мерчантов.
- 1%комиссия с платежа, без абонентской платы — из вашей суммы или сверху для покупателя
- 1запрос к API — и у бота есть ссылка на оплату или адрес с точной суммой
- ~10 сподтверждается тестовый счёт: проверка бота без реальных денег
Как проходит оплата в боте
От кнопки «Купить» до выдачи товара
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. Покажите оплату: ссылкой или прямо в чате
Два способа показать счёт в боте
- Счётсоздан без монеты
- Кнопка«Оплатить» со ссылкой на страницу оплаты
- Страница оплатыпокупатель сам выбирает монету и сеть
- Статусстраница обновляется сама
- Монетыбот показывает их кнопками из ответа API
- Выбормонета передаётся в API
- Сообщениеадрес и точная сумма из ответа API
- Ответбот пишет «оплачено» по вебхуку
- Ссылка. В ответе 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 шлёт вебхук. Для бота главные события:
Что бот делает на каждое событие
- Монета выбрана
invoice.awaiting. Счёт ждёт перевод — адрес и сумма уже известны. - Пришло меньше
invoice.underpaid. Попросите доплатить остатокpayment.remaining_amountна тот же адрес. - Оплачено
invoice.paid. Перечитайте счёт через API и выдайте товар. - Доплаты не было
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 — в документации.