Посібники

WHMCS

Платіжний шлюз для WHMCS: клієнти сплачують рахунки біткоїном або USDC/USDT просто на ваш гаманець, оплату записує підписаний вебхук.

Відкрити як Markdown

Модуль Perly Pay додає криптовалюту до рахунків WHMCS. Клієнт натискає Сплатити криптовалютою; залишок рахунку стає рахунком у Perly Pay, який сплачують поверх сторінки WHMCS або на окремій сторінці; підписаний вебхук записує оплату у WHMCS. WHMCS 8, PHP 8.1+ з curl. Через Composer нічого ставити не треба: PHP SDK уже всередині.

Perly Pay виставляє рахунки в USD або EUR. Для клієнтів з іншою валютою виберіть у шлюзі Convert To For Processing USD або EUR; оплата все одно запишеться у валюті самого рахунку. Без цього такі клієнти побачать підказку обрати інший спосіб оплати.

Встановлення

1
Отримайте zip
Модуль уже на шляху до WHMCS Marketplace. Доки його там немає, напишіть нам по perly-pay-whmcs.zip.
2
Завантажте
Розпакуйте його поверх теки WHMCS. Додадуться modules/gateways/perlypay.php, modules/gateways/callback/perlypay.php і modules/gateways/perlypay/.
3
Увімкніть
Configuration → Apps & Integrations → Payment Gateways (або Setup → Payment Gateways), увімкніть Perly Pay.

Налаштування

Поле	Що вписати
Секретний ключ	Dashboard → Developers → API keys. `sk_test_…` для тестового режиму, `sk_live_…` для справжніх грошей.
Секрет підпису вебхука	`whsec_…`, з вебхука, який ви додасте для цього WHMCS (нижче).
Сторінка оплати	Оверлей відкриває оплату поверх рахунку (pay.js). Перехід веде клієнта на її сторінку. На телефонах завжди відкривається сама сторінка.
Валюти	USD і EUR або лише одна з них.

1
Вставте ключ
Збережіть і натисніть Перевірити зʼєднання в полі ключа: побачите, чи працює ключ, його режим і чи є вебхук цього WHMCS у Perly Pay.
2
Додайте вебхук
У Dashboard → Developers → Webhooks додайте адресу з налаштувань, https://your-whmcs/modules/gateways/callback/perlypay.php, з подіями рахунків і повернень. Вставте її секрет і збережіть.
3
Дозвольте оверлей
У Dashboard → Settings додайте адресу WHMCS у Sites that may embed the checkout. Без цього оверлей запропонує відкрити оплату в новій вкладці.

Перевірка

З ключем sk_test_… відкрийте неоплачений рахунок у кабінеті клієнта й натисніть Сплатити криптовалютою. Сплатіть тестовими монетами або через API — ідентифікатор рахунку є на сторінці оплати:

bash

curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'

За кілька секунд рахунок у WHMCS стає Paid. Billing → Gateway Log показує мережу, суму й посилання на транзакцію.

Як рахунки стежать за оплатами

У Perly Pay	У WHMCS
Сплачено, відправника перевірено (`invoice.fulfilled`)	Оплата на суму, яку виставили клієнту, у валюті рахунку, з ідентифікатором оплати Perly Pay (`pay_…`). WHMCS позначає рахунок Paid і робить решту як завжди.
Помічено, сплачено частково, сплачено й ще перевіряється	Рядок у Gateway Log. Без оплати.
Затримано на перевірку	Рядок у Gateway Log з причиною. Вирішіть у Perly Pay.
Сплив або скасовано	Рядок у Gateway Log. Нове натискання кнопки створить новий рахунок.
Повернення відкрито, готове, надіслано, підтверджено	Рядок у Gateway Log: що й куди надіслати.

Повторне натискання кнопки бере відкритий рахунок, доки залишок той самий. Кожна оплата записується один раз, хоч скільки разів прийде вебхук, і лише для рахунків цього WHMCS.

Повернення

Повертайте транзакцію у WHMCS як завжди: модуль відкриє повернення в Perly Pay у тій монеті, якою сплатили (таку ж частку — для часткового). Perly Pay попросить у клієнта адресу листом і перевірить її; Gateway Log скаже, що й куди надіслати. Ви надсилаєте зі свого гаманця й вставляєте ідентифікатор транзакції в Perly Pay — Perly Pay ніколи не тримає гроші.

Запуск

Увімкніть живий режим у Perly Pay і підʼєднайте публічні ключі гаманця.
Вставте ключ sk_live_…. Живі ключі й вебхуки окремі від тестових: додайте адресу зворотного виклику ще раз у живому режимі й вставте її секрет.
Додайте https-адресу WHMCS у Sites that may embed the checkout у живому режимі.
Сплатіть один невеликий справжній рахунок і поверніть його.