Что умеет модуль
- Две кнопки на счёте: Оплатить картой / PayPal (4,5%) и Оплатить криптовалютой с выбором монеты (1,5%). Любую можно выключить.
- Клиент оплачивает остаток по счёту, поэтому частично оплаченные счета тоже работают.
- Платёж зачисляется через
addInvoicePaymentтолько после того, как модуль перечитал его через API: оплачен, сумма и валюта совпадают. Номер платежа UTOPAY становится номером транзакции, поэтому дважды платёж не зачтётся. - Счета в валюте, которую UTOPAY не принимает (например, в рублях), оплачиваются в валюте из Convert To For Processing; на счёт зачисляется сумма в его собственной валюте.
- Пока счёт просто открыт, запросов к API нет: платёж создаётся только по нажатию кнопки.
Установка
- Скачайте ZIP выше и распакуйте.
- Загрузите содержимое папки
utopay-whmcsв корень WHMCS — папкаmodulesсольётся с вашей:modules/gateways/utopay.php,modules/gateways/utopay/,modules/gateways/callback/utopay.php. - В личном кабинете UTOPAY откройте Integration → API keys и создайте тестовый ключ
utopay_sk_test_…. - Админка WHMCS → System Settings → Payment Gateways → All Payment Gateways → UTOPAY.
- Вставьте ключ, выберите способы оплаты и сохраните.
- Для криптовалюты: добавьте свой EVM-кошелёк в кабинете (Project settings → Funds & payouts, раздел Crypto wallets) и перечислите монеты в настройках модуля.
Настройки
| Поле | Что делает |
|---|---|
| Secret key | utopay_sk_test_… для песочницы, utopay_sk_live_… для реальных платежей. |
| Payment options | Карта / PayPal и криптовалюта, только карта или только криптовалюта. |
| Crypto coins | Тикеры через запятую, например bep20/usdt,erc20/usdt,polygon/usdc. Полный список: https://api.utopay.app/v1/crypto/coins. |
| Card method | Пусто — выбирает клиент. Или вести всех сразу к одному способу (Stripe, PayPal, Revolut…). |
| Convert To For Processing | Стандартная опция WHMCS: валюта, в которой проводится платёж, если валюта счёта не поддерживается. |
Тестовый платёж
- С тестовым ключом откройте неоплаченный счёт в кабинете клиента и нажмите Оплатить картой / PayPal.
- Откроется песочница UTOPAY. Нажмите зелёную кнопку ✅ — оплата будет симулирована.
- Вы вернётесь к счёту. Через несколько секунд он станет Paid; в Billing → Gateway Log появится «Success» с номером платежа.
- Замените ключ на
utopay_sk_live_….
Как подтверждаются счета
Каждый платёж создаётся со своим адресом уведомлений: /modules/gateways/callback/utopay.php с номером счёта и суммами, подписанными ключом, выведенным из вашего секретного ключа. UTOPAY подписывает каждое событие (HMAC-SHA256) и повторяет отправку в течение шести часов, если WHMCS не ответил 2xx.
Модуль проверяет обе подписи, перечитывает платёж через API и зачисляет его, только если платёж оплачен ровно на запрошенную сумму в запрошенной валюте. Каждый шаг пишется в Gateway Log.
Если что-то не работает
- «Invalid request token» — страница счёта открыта до смены ключа; обновите счёт.
- «amount is below the minimum» — остаток меньше минимума способа или монеты; клиент может выбрать другой.
- Счёт остаётся Unpaid — WHMCS должен быть доступен из интернета, а
/modules/gateways/callback/не должен закрываться файрволом или HTTP-авторизацией. Смотрите Billing → Gateway Log. - Gateway Log: «Underpaid» — клиент перевёл меньше криптовалюты, чем нужно. Деньги уже на вашем кошельке: добавьте частичный платёж вручную.
- «currency … is not supported» — укажите в Convert To For Processing USD или EUR.
История версий
- 1.0.1 — обновлено общее ядро UTOPAY, поведение не изменилось.
- 1.0.0 — первый выпуск: карты и PayPal, криптовалюта, Convert To For Processing, русские кнопки.
SHA-256: ab17e573fe3784fb5217c408d389a51af7196173d29f79d287938f9320a4327a
Обновлено · Команда интеграций UTOPAY