Приём USDT в BILLmanager: криптоплатежи для хостинга по шагам

Клиенты хостинга и VPS часто хотят платить криптой, и чаще всего — в USDT. В этом гайде — как добавить криптовалюту способом оплаты в BILLmanager 6: клиент выбирает SnapEX Pay (криптовалюта) при пополнении баланса или оплате заказа, платит в USDT в сетях TRON, Ethereum или BSC или другой монетой, и платёж зачисляется в BILLmanager автоматически. Свой кошелёк и нода блокчейна не нужны — деньги приходят на баланс мерчанта SnapEX Pay в USDT.

Как проходит платёж

клиент → пополнение или заказ → SnapEX Pay
BILLmanager → SnapEX Pay: счёт в USD
клиент → платит на странице SnapEX Pay
SnapEX Pay → подписанный вебхук → BILLmanager
модуль → GET счёта через API → paid?
BILLmanager: платёж зачислен

1. Клиент выбирает SnapEX Pay (криптовалюта) среди способов оплаты. Модуль создаёт счёт SnapEX Pay на сумму платежа в USD и отправляет клиента на страницу оплаты.
2. Клиент выбирает монету и сеть и платит. Когда счёт оплачен, SnapEX Pay шлёт вашему биллингу подписанный вебхук.
3. Модуль перечитывает счёт через API SnapEX Pay и зачисляет платёж, только если счёт в статусе paid и сумма совпадает. Одно лишь тело вебхука ничего не зачисляет.

Платёж зачисляется тремя независимыми способами — каким сработает первым: подписанным вебхуком, при возврате клиента со страницы оплаты и периодической проверкой (checkpay, раз в 5 минут). Потерянный вебхук не оставит оплаченный платёж незачисленным, и дважды платёж не зачтётся.

Что нужно

• BILLmanager 6 любой редакции и root-доступ к его серверу.
• python3 3.6+ на этом сервере. Модулю хватает стандартной библиотеки: никаких дополнительных пакетов, billmanager-plugin-python-libs не нужен.
• Метод оплаты в USD: счета SnapEX Pay выставляются в долларах.
• Аккаунт мерчанта SnapEX Pay: регистрация на pay.snapex.pro.

Шаг 1. Установите модуль

Скачайте snapexpay-billmanager-1.1.0.tar.gz (бесплатно) и выполните на сервере BILLmanager под root:

curl -fsSLO https://pay.snapex.pro/downloads/billmanager/snapexpay-billmanager-1.1.0.tar.gz
tar xzf snapexpay-billmanager-1.1.0.tar.gz
cd snapexpay-billmanager-1.1.0
sh install.sh

Скрипт копирует модуль в /usr/local/mgr5, добавляет страховочный cron checkpay раз в 5 минут (/etc/cron.d/snapexpay) и перезапускает BILLmanager. Если BILLmanager или python3 3.6+ не найдены, он остановится с сообщением.

Шаг 2. Получите API-ключ

В кабинете мерчанта SnapEX Pay откройте «Разработчикам» и выпустите API-ключ. Модулю нужны права invoices.read и invoices.write; ключ из кабинета получает все права Merchant API, в том числе эти. Ключ показывается один раз — сразу скопируйте его. Перевыпуск сразу отзывает старый ключ, поэтому меняйте его в методе оплаты в тот же момент.

Шаг 3. Добавьте метод оплаты

В BILLmanager откройте Provider → Payment methods → Add (в русском интерфейсе — соответствующие пункты) и выберите SnapEX Pay (криптовалюта). Укажите валюту USD и вставьте API-ключ.

При сохранении ключ проверяется в SnapEX Pay: с неверным или отозванным ключом, а также с валютой не USD метод не сохранится.

Остальные настройки:

• Комиссию сети платит клиент — выключено: клиент платит ровно сумму платежа, а комиссии удерживаются из поступления; включено: комиссия SnapEX Pay и сетевая комиссия добавляются клиенту сверху. Подробно: Кто платит комиссию за криптоплатёж.
• Время на оплату, минут — сколько действует страница оплаты SnapEX Pay: от 1 до 1440, по умолчанию 60. Если клиент откроет платёж позже, создастся новая страница.
• Тестовый режим — см. шаг 6.
• Partner ID — см. шаг 5.
• Адрес API — оставьте пустым.

Клиенты платят в рублях или другой валюте? BILLmanager пересчитывает сумму в валюту метода оплаты (USD) по своим курсам — следите, чтобы курс USD был актуальным.

Шаг 4. Настройте вебхук

Вебхук необязателен, но рекомендуется: с ним баланс зачисляется сразу после подтверждения оплаты.

1. В кабинете на странице «Разработчикам» укажите адрес вебхука https://<домен биллинга>/mancgi/snapexpayresult и сохраните.
2. Секрет подписи whsec_… показывается один раз, сразу после первого сохранения. Вставьте его в поле «Секрет вебхука» в настройках метода оплаты.

Как модуль проверяет уведомление:

• заголовок Webhook-Signature: HMAC-SHA256 от {Webhook-Timestamp}.{сырое тело запроса} с вашим секретом; неподписанные или подменённые запросы получают 401;
• Webhook-Timestamp в пределах 5 минут от часов сервера — держите NTP включённым;
• сам счёт, перечитанный через API SnapEX Pay вашим ключом.

Если API в этот момент недоступен, модуль отвечает 502, и SnapEX Pay повторяет доставку. В кабинете один адрес вебхука на аккаунт; события по счетам, которые создал не этот биллинг, модуль пропускает. Без вебхука платежи всё равно зачисляются при возврате клиента со страницы оплаты и проверкой раз в 5 минут. Подробнее о подписи и повторах: Вебхуки криптоплатежей.

Шаг 5. Partner ID: кто настроил модуль

Поле Partner ID необязательное. Если вы ставите модуль для своего хостинга, оставьте его пустым.

Если вы интегратор и настраиваете биллинг клиентам, впишите свой Partner ID: аккаунт мерчанта клиента закрепится за вами, и вы будете получать 35% нашей комиссии с платежей этого клиента. Клиент создаёт свой аккаунт SnapEX Pay и API-ключ, деньги идут на его баланс. Условия: Партнёрская программа SnapEX Pay.

Шаг 6. Тестовый платёж без реальных денег

1. Создайте отдельный метод оплаты с включённым тестовым режимом и сделайте его доступным только тестовому клиенту (Payment methods → ограничения по группе клиентов).
2. Войдите тестовым клиентом, начните пополнение баланса и выберите этот метод.
3. На странице SnapEX Pay будет метка Test. Выберите любую монету и сеть: страница покажет тестовый адрес, и примерно через 10 секунд оплата подтвердится сама. Ничего отправлять не нужно.
4. Платёж в BILLmanager должен стать зачисленным. Если нет — смотрите /usr/local/mgr5/var/pmsnapexpay.log и журнал доставок на странице «Разработчикам».
5. Выключите тестовый режим или удалите тестовый метод оплаты.

После выключения тестового режима тестовые платежи не зачисляются — тестовыми деньгами нельзя оплатить настоящие услуги. Подробнее: Как протестировать криптоплатежи без реальных денег.

Что видит клиент

• Среди способов оплаты при пополнении или оплате заказа — SnapEX Pay (криптовалюта).
• Страницу оплаты SnapEX Pay: USDT в TRC20, ERC20 и BEP20 и другие монеты (всего 50+), если SnapEX Pay предлагает их для суммы счёта.
• После оплаты клиент возвращается в биллинг. Если платёж уже подтверждён, BILLmanager показывает обычную страницу успешной оплаты; если ещё нет — сообщение «Thank you! Your payment is being confirmed on the blockchain» («Спасибо! Платёж подтверждается в блокчейне») и ссылку обратно к платежам: баланс зачислится автоматически.
• Если клиент ушёл и снова открыл платёж, пока не истекло время на оплату, он попадёт на ту же страницу, а не получит второй счёт.

Что появляется в BILLmanager

• Клиент открыл оплату → платёж переходит в статус In payment, внешний ID — номер счёта SnapEX Pay (INV-…).
• Оплачен полностью → платёж зачислен; в поле информации — монета, сеть и полученная сумма.
• Оплачен частично (клиент прислал меньше и не доплатил вовремя) → ничего не зачисляется, в логе — closed with a PARTIAL payment (…) - review in SnapEX Pay and credit manually. Полученное лежит на вашем балансе SnapEX Pay. Как работают недоплаты: Клиент прислал меньше суммы счёта.
• Не оплачен вовремя → платёж остаётся In payment, чтобы клиент мог попробовать снова; через сутки после истечения последнего счёта SnapEX Pay он отменяется.
• Оплачен дважды, оплачен после отмены платежа или доплата после закрытия счёта → запись в логе; деньги на вашем балансе SnapEX Pay.

Если что-то не работает

• Метод оплаты не сохраняется. Проверьте API-ключ (неверный или отозван) и валюту: подходит только USD.
• Клиент видит «Crypto payments are not available for this currency». Валюта метода оплаты — не USD.
• Клиент видит «Could not start the crypto payment». SnapEX Pay не создал счёт; причина — в pmsnapexpay.log.
• Вебхук получает 401. Не совпадает секрет вебхука или часы сервера сбиты.
• Вебхук получает 503 «webhook secret is not configured». Адрес вебхука в кабинете указан, а поле «Секрет вебхука» в методе оплаты пустое.
• Клиент оплатил, а баланс не пополнился. Найдите платёж в /usr/local/mgr5/var/pmsnapexpay.log: частичная оплата и оплата уже отменённого платежа автоматически не зачисляются.

Удалить модуль — sh install.sh --uninstall из распакованного архива. История платежей останется в /usr/local/mgr5/var/snapexpay.sqlite.

Сколько стоит

1% с платежа, без платы за подключение и абонентской платы. Модуль бесплатный.

Страница модуля: BILLmanager. Выбираете шлюз для хостинга: Как выбрать криптошлюз для хостинга. Обзор для хостингов: Криптоплатежи для хостинга. Регистрация: pay.snapex.pro.