Приём USDT в WHMCS: криптовалютный платёжный шлюз по шагам

Клиенты хостинга, VPS и доменов всё чаще просят оплату криптой, и чаще всего — в USDT. В этом гайде — как добавить криптовалюту платёжным шлюзом в WHMCS 8.x или 9.x: клиент открывает неоплаченный счёт, нажимает Pay Now, платит на странице SnapEX Pay в USDT в сетях TRON, Ethereum, BSC, Solana, TON, Polygon и других или другой монетой, и WHMCS сам отмечает счёт оплаченным. Свой кошелёк и нода блокчейна не нужны — деньги приходят на баланс мерчанта SnapEX Pay в USDT.

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

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

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

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

Что нужно

• WHMCS 8.x или 9.x с работающим системным cron (тем же, что нужен самому WHMCS для автоматизации).
• PHP 7.4 или новее с cURL.
• HTTPS на адресе WHMCS — иначе SnapEX Pay не сможет доставлять вебхуки.
• Аккаунт мерчанта SnapEX Pay: регистрация на pay.snapex.pro.

Шаг 1. Загрузите модуль

Скачайте snapexpay-whmcs-1.1.0.zip (бесплатно) и распакуйте в корень WHMCS с сохранением путей. По SSH:

cd /path/to/whmcs
curl -fsSLO https://pay.snapex.pro/downloads/whmcs/snapexpay-whmcs-1.1.0.zip
unzip snapexpay-whmcs-1.1.0.zip -x README.md
rm snapexpay-whmcs-1.1.0.zip

Должны появиться файлы:

modules/gateways/snapexpay.php
modules/gateways/snapexpay/
modules/gateways/callback/snapexpay.php
includes/hooks/snapexpay.php

Файл в includes/hooks/ — это проверка по cron; без него платежи всё равно зачисляются вебхуком и при возврате клиента, но страховки не будет. Через FTP или файловый менеджер хостинга загрузите те же папки поверх корня WHMCS. Свою таблицу модуль создаёт сам при первом запуске — в базе руками ничего делать не нужно.

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

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

Шаг 3. Включите шлюз

В админке WHMCS откройте System Settings → Payment Gateways → All Payment Gateways и нажмите SnapEX Pay (Crypto). Затем на вкладке Manage Existing Gateways заполните поля:

Клиент видит шлюз как SnapEX Pay (Crypto); название можно поменять в поле Display Name (например, «Криптовалюта (USDT)»).

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

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

1. Скопируйте адрес вебхука, который WHMCS показывает под полем Webhook secret. Он вида https://<ваш WHMCS>/modules/gateways/callback/snapexpay.php.
2. В кабинете на странице «Разработчикам» вставьте его адресом вебхука и сохраните.
3. Секрет подписи whsec_… показывается один раз, сразу после первого сохранения. Вставьте его в поле Webhook secret в WHMCS и сохраните шлюз.

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

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

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

Шаг 5. Если WHMCS выставляет счета не в долларах

Счета SnapEX Pay — в долларах США. Если основная валюта у вас рубли, евро или другая:

1. Проверьте, что USD есть в System Settings → Currencies и курс актуален (WHMCS умеет обновлять курсы сам).
2. В настройках шлюза установите Convert To For Processing = USD.

Клиент платит эквивалент в долларах, а платёж по-прежнему записывается в счёт в валюте клиента, на полную сумму к оплате. Без этой настройки вместо кнопки Pay Now клиент увидит надпись SnapEX Pay: set "Convert To For Processing" to USD in the gateway settings.

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

1. Включите Test mode в настройках шлюза. Теперь начать оплату может только тот, кто вошёл в админку WHMCS; остальные клиенты вместо кнопки видят SnapEX Pay is in test mode — никто случайно не оплатит настоящий счёт.
2. В том же браузере откройте неоплаченный счёт тестового клиента (например, через Login as Owner в профиле клиента) и нажмите Pay Now — рядом будет пометка (test mode).
3. На странице SnapEX Pay — метка Test. Выберите любую монету и сеть: страница покажет тестовый адрес, и примерно через 10 секунд платёж подтвердится сам. Ничего отправлять не нужно.
4. Счёт должен стать Paid, а в Billing → Gateway Log появится запись Successful. Если нет — смотрите этот журнал и журнал доставок на странице «Разработчикам» в кабинете.
5. Выключите тестовый режим.

Тестовые платежи не зачитываются после выключения тестового режима (в журнале — Test payment while test mode is off — not applied), так что тестовыми деньгами нельзя оплатить настоящие услуги. Подробно: Как протестировать криптоплатежи без денег.

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

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

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

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

• В неоплаченном счёте — SnapEX Pay (Crypto) среди способов оплаты и кнопку Pay Now.
• Страницу оплаты SnapEX Pay: USDT в сетях TRC20, ERC20, BEP20, Solana, TON, Polygon и других, а также другие монеты (60+ всего), если SnapEX Pay предлагает их для суммы счёта.
• После оплаты клиент возвращается в счёт. Если платёж уже подтверждён, WHMCS сразу показывает его оплаченным; если нет — счёт станет Paid по вебхуку или при следующей проверке cron.
• Повторное нажатие Pay Now, пока страница оплаты действует, открывает ту же страницу, а не второй счёт. После её истечения создаётся новая.

Что попадает в WHMCS

• Оплачено полностью → платёж добавляется в счёт в валюте счёта, счёт становится Paid. Номер транзакции — ID счёта SnapEX Pay (INV-…), по нему платёж легко найти в кабинете.
• Оплачено частично (клиент прислал меньше и не доплатил вовремя) → автоматически ничего не добавляется; в Gateway Log — Partial payment — review and apply manually с монетой, сетью и полученной суммой. Полученное лежит на вашем балансе SnapEX Pay; если принимаете его, добавьте платёж в WHMCS вручную. Как устроены недоплаты: Клиент заплатил меньше суммы счёта.
• Не оплачено вовремя → в Gateway Log — Expired, счёт WHMCS остаётся Unpaid, клиент может снова нажать Pay Now.
• Лишний платёж после закрытия счёта SnapEX Pay → если настроен вебхук, в Gateway Log — Extra payment received — check the SnapEX Pay cabinet; деньги на вашем балансе SnapEX Pay.
• Счёт изменился после того, как клиент открыл оплату (например, вы добавили позицию) → старый платёж не зачитывается в новую сумму (Amount mismatch — not applied); клиент нажимает Pay Now ещё раз на новую сумму.

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

• Клиент видит «set Convert To For Processing to USD». Шаг 5: валюта счёта не USD, а конвертация не задана.
• Клиенты не видят кнопку, только «SnapEX Pay is in test mode». Не выключен тестовый режим.
• «Could not start the crypto payment: …». SnapEX Pay отклонил счёт — чаще всего неверный или отозванный API-ключ; причина — в сообщении и в Gateway Log (Error creating payment).
• Вебхук получает 401. Webhook secret в WHMCS не совпадает с секретом из кабинета.
• Вебхук получает 400 «stale or missing timestamp». Сбиты часы сервера.
• Вебхук получает 503. Либо шлюз не включён в WHMCS, либо адрес в кабинете указан, а поле Webhook secret пустое.
• Оплаченный счёт становится Paid не сразу. Вебхука нет — платёж подхватила проверка по cron. Настройте шаг 4 и проверьте, что cron WHMCS запускается.

Всё, что делает модуль, — в Billing → Gateway Log. Чтобы удалить модуль, отключите шлюз в WHMCS и удалите четыре пути из шага 1.

Стоимость

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

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