# WHMCS

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

Модуль Perly Pay додає криптовалюту до рахунків WHMCS. Клієнт натискає **Сплатити криптовалютою**; залишок рахунку стає рахунком у Perly Pay, який сплачують поверх сторінки WHMCS або на окремій сторінці; підписаний вебхук записує оплату у WHMCS. WHMCS 8, PHP 8.1+ з curl. Через Composer нічого ставити не треба: [PHP SDK](https://pay.perly.io/docs/sdks.md) уже всередині.

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

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

1. **Отримайте zip** — Модуль уже на шляху до WHMCS Marketplace. Доки його там немає, [напишіть нам](https://pay.perly.io/uk/contact) по `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_…` для [тестового режиму](https://pay.perly.io/docs/test-mode.md), `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. Без оплати. |
| Затримано на [перевірку](https://pay.perly.io/docs/screening.md) | Рядок у Gateway Log з причиною. Вирішіть у Perly Pay. |
| Сплив або скасовано | Рядок у Gateway Log. Нове натискання кнопки створить новий рахунок. |
| Повернення відкрито, готове, надіслано, підтверджено | Рядок у Gateway Log: що й куди надіслати. |

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

## Повернення

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

## Запуск

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