# WooCommerce

> Metoda płatności dla WooCommerce: bitcoin i USDC/USDT prosto na Twój portfel, zamówienie oznacza jako opłacone podpisany webhook.

Wtyczka Perly Pay dodaje kryptowaluty do klasycznego zamówienia i do bloku Checkout. Każde zamówienie staje się fakturą w Perly Pay; kupujący opłaca ją nad sklepem lub na osobnej stronie; podpisany webhook oznacza zamówienie jako opłacone. WordPress 6.5+, WooCommerce 8.6+, PHP 8.1+. Na serwerze nic nie trzeba instalować: [PHP SDK](https://pay.perly.io/docs/sdks.md) jest już w środku.

> **Uwaga:** Faktury są w USD lub EUR. W sklepie z inną walutą metoda płatności jest ukryta, a jej ustawienia wyjaśniają dlaczego.

## Instalacja

1. **Zdobądź zip** — Wtyczka jest już w drodze do WordPress.org. Dopóki jej tam nie ma, [napisz do nas](https://pay.perly.io/pl/contact) po `perly-pay-woocommerce.zip`.
2. **Zainstaluj** — W WordPressie: Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer, wybierz zip, włącz. WooCommerce musi być aktywny.
3. **Otwórz ustawienia** — WooCommerce → Ustawienia → Płatności → **Perly Pay**.

## Konfiguracja

| Pole | Co wpisać |
| --- | --- |
| Klucz tajny | Dashboard → Developers → API keys. `sk_test_…` dla [trybu testowego](https://pay.perly.io/docs/test-mode.md), `sk_live_…` dla prawdziwych pieniędzy. Ustawienia pokazują, w jakim jesteś trybie. |
| Sekret podpisu webhooka | `whsec_…`. **Skonfiguruj webhook** wypełni go sam. |
| Strona płatności | **Okno** otwiera płatność nad sklepem (pay.js). **Przekierowanie** prowadzi kupującego na jej stronę. Na telefonach zawsze otwiera się sama strona. |
| Status po zapłacie | Jak zdecyduje WooCommerce (Przetwarzane; Zrealizowane dla plików do pobrania), zawsze Przetwarzane albo zawsze Zrealizowane. |
| Nazwa, Opis | Co widzą kupujący podczas składania zamówienia. |
| Log debugowania | Zdarzenia i błędy w WooCommerce → Status → Logi. Nigdy klucze, sekrety ani dane kupujących. |

1. **Wklej klucz** — I kliknij **Sprawdź połączenie**: zobaczysz, czy klucz działa, jego tryb i czy webhook tego sklepu jest w Perly Pay.
2. **Skonfiguruj webhook** — Kliknij **Skonfiguruj webhook**. Doda adres sklepu (jest nad przyciskami, `…/wp-json/perly-pay/v1/webhook`) w Perly Pay i zapisze sekret. Albo dodaj go sam w Developers → Webhooks i wklej sekret.
3. **Dopuść okno** — W Dashboard → Settings dodaj adres sklepu w **Sites that may embed the checkout**. Bez tego okno zaproponuje otwarcie płatności w nowej karcie.
4. **Włącz** — Zaznacz **Przyjmuj kryptowaluty przez Perly Pay** i zapisz.

## Testowanie

Z kluczem `sk_test_…` złóż zamówienie w swoim sklepie i wybierz Perly Pay. Zamówienie czeka jako **Oczekujące na płatność**. Opłać fakturę monetami testowymi albo przez API — jej identyfikator jest w notatkach zamówienia:

```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 '{}'
```

Po kilku sekundach zamówienie staje się **Przetwarzane**, z notatką: sieć, kwota i link do transakcji. `{"outcome":"short"}` i `{"outcome":"over"}` sprawdzają inne przypadki, gdy moneta na stronie faktury jest już wybrana.

## Jak zamówienia śledzą płatności

| W Perly Pay | Zamówienie |
| --- | --- |
| Opłacona, nadawca sprawdzony (`invoice.fulfilled`) | Opłacone: wybrany status, stany magazynowe zmniejszone, e-mail do kupującego. Notatka z każdym przelewem i jego transakcją. |
| Widoczna, opłacona częściowo, opłacona i jeszcze sprawdzana | Notatka. Dalej czeka. |
| Wstrzymana do [sprawdzenia](https://pay.perly.io/docs/screening.md) | Wstrzymane, z powodem. Zdecyduj w Perly Pay. |
| Wygasła lub anulowana, nic nie zapłacono | Anulowane. |
| Wygasła, opłacona częściowo | Wstrzymane: zwróć lub zaakceptuj w Perly Pay. |
| Zwrócona | Zwrócone w całości albo notatka o części. |

Każde zdarzenie jest stosowane raz, do zamówienia, dla którego je utworzono, a spóźnione „wygasła” nigdy nie anuluje płatności. Jeśli kupujący wrócił na stronę podziękowania przed webhookiem, wtyczka zapyta API i od razu zaktualizuje zamówienie.

## Zwroty

Zwracaj jak zwykle, ze strony zamówienia: wtyczka otworzy [zwrot](https://pay.perly.io/docs/refunds.md) w Perly Pay w monecie, którą zapłacono (część — przy częściowym). Perly Pay poprosi kupującego e-mailem o adres i go sprawdzi; notatki zamówienia powiedzą, co i dokąd wysłać. Wysyłasz ze swojego portfela i wklejasz identyfikator transakcji w Perly Pay — Perly Pay nigdy nie przechowuje pieniędzy.

## Start

- Włącz tryb produkcyjny w Perly Pay i podłącz klucze publiczne portfela.
- Wklej klucz `sk_live_…`. Klucze i webhooki produkcyjne są oddzielne od testowych: kliknij **Skonfiguruj webhook** jeszcze raz.
- Dodaj adres https produkcyjnego sklepu w **Sites that may embed the checkout** w trybie produkcyjnym.
- Złóż jedno małe prawdziwe zamówienie i je zwróć.