Poradniki

WooCommerce

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

Otwórz jako Markdown

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 jest już w środku.

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 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, `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	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 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óć.