Що вміє модуль
- Дві кнопки на рахунку: Pay by card / PayPal (4,5%) і Pay with crypto з вибором монети (1,5%). Будь-яку можна вимкнути.
- Клієнт оплачує залишок за рахунком, тому частково оплачені рахунки теж працюють.
- Платіж зараховується через
addInvoicePaymentлише після того, як модуль перечитав його через API: оплачено, сума й валюта збігаються. Номер платежу UTOPAY стає номером транзакції, тому платіж ніколи не зарахується двічі. - Рахунки у валюті, яку UTOPAY не приймає (наприклад, RUB), оплачуються у валюті з 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: валюта, в якій проводиться платіж, якщо валюта рахунку не підтримується. |
Тестовий платіж
- З тестовим ключем відкрийте неоплачений рахунок у кабінеті клієнта й натисніть Pay by card / 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