Криптоплатежи в Xboard и V2Board: приём USDT за VPN-подписки по шагам

Xboard и V2Board — популярные панели для продажи VPN- и прокси-подписок. Из коробки клиент платит картой или через шлюз, который вы держите сами. В этом гайде — как добавить крипту: клиент платит в USDT в сетях TRC20, ERC20 или BEP20 или другой монетой, а панель сама открывает заказ. Свой кошелёк, нода или самописный шлюз не нужны — деньги приходят на баланс мерчанта SnapEX Pay.

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

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

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

Что нужно

• Xboard с системой плагинов (PHP 8.2+) или V2Board / старый Xboard, который берёт шлюзы из app/Payments (PHP 7.3+).
• Расширение PHP cURL.
• Панель доступна из интернета по HTTPS: SnapEX Pay доставляет вебхуки только на публичные HTTPS-адреса.
• Аккаунт мерчанта SnapEX Pay: регистрация на pay.snapex.pro.

Шаг 1. Установите плагин

Скачайте архив snapexpay-xboard-1.2.0.zip (MIT, бесплатно).

Xboard. Админка → Плагины → загрузить ZIP → Установить → Включить «SnapEX Pay». Или распакуйте архив в папку панели:

cd /path/to/Xboard
curl -fsSLO https://pay.snapex.pro/downloads/xboard/snapexpay-xboard-1.2.0.zip
unzip snapexpay-xboard-1.2.0.zip
mv snapexpay-xboard-1.2.0 plugins/Snapexpay

Папка должна называться ровно plugins/Snapexpay — в Linux регистр букв важен. Затем Плагины → Установить → Включить.

V2Board и старый Xboard. Скопируйте из архива один файл в панель:

unzip -p snapexpay-xboard-1.2.0.zip \
  snapexpay-xboard-1.2.0/app/Payments/SnapexPay.php \
  > /path/to/v2board/app/Payments/SnapexPay.php

Если у вас OPcache или Octane, перезапустите PHP-FPM или Octane. Проверьте, что в настройках V2Board заполнен адрес сайта (app_url): без него плагин не сможет вернуть клиента на страницу заказа после оплаты.

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

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

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

Админка панели → Настройки оплаты → Добавить способ оплаты → шлюз SnapexPay. Поля:

• API key — ключ из шага 2.
• Webhook secret — заполните на шаге 4.
• Network fee paid by — merchant (по умолчанию): клиент платит ровно сумму заказа; customer: сетевая комиссия добавляется сверху. Подробно: Кто платит комиссию за криптоплатёж.
• Payment window, minutes — сколько минут счёт можно оплатить. Xboard: по умолчанию 60, максимум 120; V2Board: по умолчанию 20, максимум 30. Предел ниже тайм-аута самой панели для неоплаченных заказов, чтобы клиент не оплатил заказ, который панель уже отменила.
• USD per 1 shop currency — 1, если цены в USD. Панели хранят суммы в центах, плагин отправляет total / 100 × usd_rate. Для магазина в CNY это около 0.14. Курс фиксированный: когда курс валюты меняется, обновляйте его сами.
• Environment — live или test (см. шаг 5).
• Partner ID — оставьте пустым, если настраиваете сами; интегратор, который вас подключил, вписывает сюда свой ID.
• API URL — оставьте по умолчанию https://snapex.pro/api/v1/merchant.

Минимальный счёт — 0.50 USD: заказ меньше этой суммы (после пересчёта) выдаст ошибку при оформлении.

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

У каждого способа оплаты в панели свой notify-адрес:

https://your-panel.example/api/v1/guest/payment/notify/SnapexPay/{uuid}

Xboard показывает полный адрес в списке способов оплаты. В кабинете на странице «Разработчикам» вставьте его как адрес вебхука и сохраните. Секрет подписи whsec_… показывается один раз, сразу после первого сохранения, — скопируйте его в Webhook secret способа оплаты.

В кабинете один адрес вебхука на аккаунт, и туда приходят все события. Плагин открывает заказ только по оплаченному счёту; на остальные события панель отвечает ошибкой (422 в Xboard, 500 в V2Board). В журнале доставок это выглядит как неудачная доставка — так и должно быть.

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

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

Подробнее о подписи и повторах: Вебхуки криптоплатежей.

Шаг 5. Тестовый заказ без реальных денег

1. Поставьте Environment = test и сохраните.
2. Создайте заказ в панели и перейдите к оплате.
3. На странице SnapEX Pay будет метка Test. Выберите любую монету и сеть: страница покажет тестовый адрес, и примерно через 10 секунд оплата подтвердится сама. Ничего отправлять не нужно.
4. Заказ должен стать оплаченным за несколько секунд. Если нет — смотрите журнал доставок на странице «Разработчикам» и лог панели (storage/logs).
5. Верните Environment = live.

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

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

Страницу SnapEX Pay с выбором монеты: USDT в TRC20, ERC20 и BEP20 и другие монеты (всего 50+), если SnapEX Pay предлагает их для суммы счёта. Если клиент снова нажмёт «Оплатить», откроется тот же счёт, пока он действует; если срок вышел — для того же заказа создаётся новый (external_id {trade_no}-1, -2 и так далее).

Если клиент прислал меньше суммы, заказ не откроется: полученное придёт на ваш баланс SnapEX Pay, остаток вы решаете с клиентом сами. Как работают недоплаты: Клиент прислал меньше суммы счёта.

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

• SnapexPay нет в списке шлюзов (Xboard). Папка должна быть ровно plugins/Snapexpay, плагин — и установлен, и включён.
• При оформлении «A valid merchant API key is required» или «This source IP is not allowed». Ключ неверный или отозван, либо в его списке разрешённых IP нет исходящего IP сервера панели.
• «Amount is below the … USD minimum». После пересчёта заказ меньше 0.50 USD — проверьте USD per 1 shop currency.
• Клиент оплатил, а заказ не оплачен. Посмотрите журнал доставок в кабинете. Обычно не совпадает webhook secret, часы сервера ушли больше чем на 5 минут, адрес указывает на UUID другого способа оплаты, обратный прокси меняет тело запроса или панель не может достучаться до API SnapEX Pay. Неудачную доставку можно повторить из журнала.

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

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

Страница плагина: Xboard / V2Board. Обзор для VPN-сервисов: Криптоплатежи для VPN-сервисов. Регистрация: pay.snapex.pro.