# WooCommerce

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

Плагін Perly Pay додає криптовалюту в класичне оформлення й у блок Checkout. Кожне замовлення стає рахунком у Perly Pay; покупець сплачує його поверх магазину або на окремій сторінці; підписаний вебхук позначає замовлення сплаченим. WordPress 6.5+, WooCommerce 8.6+, PHP 8.1+. На сервер нічого ставити не треба: [PHP SDK](https://pay.perly.io/docs/sdks.md) уже всередині.

> **Примітка:** Рахунки — у USD або EUR. У магазині з іншою валютою спосіб оплати прихований, а його налаштування пояснюють чому.

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

1. **Отримайте zip** — Плагін уже на шляху до WordPress.org. Доки його там немає, [напишіть нам](https://pay.perly.io/uk/contact) по `perly-pay-woocommerce.zip`.
2. **Встановіть** — У WordPress: Плагіни → Додати новий → Завантажити плагін, оберіть zip, активуйте. WooCommerce має бути активним.
3. **Відкрийте налаштування** — WooCommerce → Налаштування → Платежі → **Perly Pay**.

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

| Поле | Що вписати |
| --- | --- |
| Секретний ключ | Dashboard → Developers → API keys. `sk_test_…` для [тестового режиму](https://pay.perly.io/docs/test-mode.md), `sk_live_…` для справжніх грошей. Налаштування показують, у якому ви режимі. |
| Секрет підпису вебхука | `whsec_…`. **Налаштувати вебхук** заповнить його сам. |
| Сторінка оплати | **Вікно** відкриває оплату поверх магазину (pay.js). **Перехід** веде покупця на її сторінку. На телефонах завжди відкривається сама сторінка. |
| Статус після оплати | Як вирішить WooCommerce (Обробляється; Виконано для завантажень), завжди Обробляється або завжди Виконано. |
| Назва, Опис | Що бачать покупці під час оформлення. |
| Журнал налагодження | Події й помилки в WooCommerce → Стан → Журнали. Ніколи ключі, секрети чи дані покупців. |

1. **Вставте ключ** — І натисніть **Перевірити з'єднання**: побачите, чи працює ключ, його режим і чи є вебхук цього магазину в Perly Pay.
2. **Налаштуйте вебхук** — Натисніть **Налаштувати вебхук**. Він додасть адресу магазину (вона над кнопками, `…/wp-json/perly-pay/v1/webhook`) у Perly Pay і збереже секрет. Або додайте її самі в Developers → Webhooks й вставте секрет.
3. **Дозвольте вікно** — У Dashboard → Settings додайте адресу магазину в **Sites that may embed the checkout**. Без цього вікно запропонує відкрити оплату в новій вкладці.
4. **Увімкніть** — Позначте **Приймати криптовалюту через Perly Pay** і збережіть.

## Перевірка

З ключем `sk_test_…` оформіть замовлення у своєму магазині й оберіть Perly Pay. Замовлення чекає як **Очікує оплати**. Сплатіть рахунок тестовими монетами або через 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 '{}'
```

За кілька секунд замовлення стає **Обробляється**, з нотаткою: мережа, сума й посилання на транзакцію. `{"outcome":"short"}` і `{"outcome":"over"}` перевіряють інші випадки, коли монету на сторінці рахунку вже обрано.

## Як замовлення стежать за оплатами

| У Perly Pay | Замовлення |
| --- | --- |
| Сплачено, відправника перевірено (`invoice.fulfilled`) | Сплачено: обраний статус, залишки зменшено, лист покупцю. Нотатка з кожним переказом і його транзакцією. |
| Помічено, сплачено частково, сплачено й ще перевіряється | Нотатка. Далі очікує. |
| Затримано на [перевірку](https://pay.perly.io/docs/screening.md) | На утриманні, з причиною. Вирішіть у Perly Pay. |
| Сплив або скасовано, нічого не сплачено | Скасовано. |
| Сплив, сплачено частково | На утриманні: поверніть або прийміть у Perly Pay. |
| Повернено | Повернено повністю або нотатка про частину. |

Кожна подія застосовується один раз, до того замовлення, для якого її створено, а пізнє «сплив» ніколи не скасує оплату. Якщо покупець повернувся на сторінку подяки раніше за вебхук, плагін запитає API й оновить замовлення одразу.

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

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

## Запуск

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