Poradniki
WHMCS
Bramka płatności dla WHMCS: klienci opłacają faktury bitcoinem lub USDC/USDT prosto na Twój portfel, płatność zapisuje podpisany webhook.
Moduł Perly Pay dodaje kryptowaluty do faktur WHMCS. Klient klika Zapłać kryptowalutą; saldo faktury staje się fakturą w Perly Pay, opłacaną nad stroną WHMCS lub na osobnej stronie; podpisany webhook zapisuje płatność w WHMCS. WHMCS 8, PHP 8.1+ z curl. Przez Composer nic nie trzeba instalować: PHP SDK jest już w środku.
Instalacja
- 1
Zdobądź zip
Moduł jest już w drodze do WHMCS Marketplace. Dopóki go tam nie ma, napisz do nas po
perly-pay-whmcs.zip. - 2
Wgraj
Rozpakuj go na katalog WHMCS. Dojdą
modules/gateways/perlypay.php,modules/gateways/callback/perlypay.phpimodules/gateways/perlypay/. - 3
Włącz
Configuration → Apps & Integrations → Payment Gateways (lub Setup → Payment Gateways), włącz Perly Pay.
Konfiguracja
| Pole | Co wpisać |
|---|---|
| Klucz tajny | Dashboard → Developers → API keys. sk_test_… dla trybu testowego, sk_live_… dla prawdziwych pieniędzy. |
| Sekret podpisu webhooka | whsec_…, z webhooka, który dodasz dla tego WHMCS (poniżej). |
| Strona płatności | Nakładka otwiera płatność nad fakturą (pay.js). Przekierowanie prowadzi klienta na jej stronę. Na telefonach zawsze otwiera się sama strona. |
| Waluty | USD i EUR albo tylko jedna z nich. |
- 1
Wklej klucz
Zapisz i kliknij Sprawdź połączenie przy polu klucza: zobaczysz, czy klucz działa, jego tryb i czy webhook tego WHMCS jest w Perly Pay.
- 2
Dodaj webhook
W Dashboard → Developers → Webhooks dodaj adres z ustawień,
https://your-whmcs/modules/gateways/callback/perlypay.php, ze zdarzeniami faktur i zwrotów. Wklej jego sekret i zapisz. - 3
Dopuść nakładkę
W Dashboard → Settings dodaj adres WHMCS w Sites that may embed the checkout. Bez tego nakładka zaproponuje otwarcie płatności w nowej karcie.
Testowanie
Z kluczem sk_test_… otwórz nieopłaconą fakturę w panelu klienta i kliknij Zapłać kryptowalutą. Zapłać monetami testowymi albo przez API — identyfikator faktury jest na stronie płatności:
Po kilku sekundach faktura w WHMCS staje się Paid. Billing → Gateway Log pokazuje sieć, kwotę i link do transakcji.
Jak faktury śledzą płatności
| W Perly Pay | W WHMCS |
|---|---|
Opłacona, nadawca sprawdzony (invoice.fulfilled) | Płatność na kwotę wystawioną klientowi, w walucie faktury, z identyfikatorem płatności Perly Pay (pay_…). WHMCS oznacza fakturę jako Paid i robi resztę jak zwykle. |
| Widoczna, opłacona częściowo, opłacona i jeszcze sprawdzana | Wiersz w Gateway Log. Bez płatności. |
| Wstrzymana do sprawdzenia | Wiersz w Gateway Log z powodem. Zdecyduj w Perly Pay. |
| Wygasła lub anulowana | Wiersz w Gateway Log. Ponowne kliknięcie przycisku utworzy nową fakturę. |
| Zwrot otwarty, gotowy, wysłany, potwierdzony | Wiersz w Gateway Log: co i dokąd wysłać. |
Ponowne kliknięcie przycisku bierze otwartą fakturę, dopóki saldo jest takie samo. Każda płatność jest zapisywana raz, niezależnie od tego, ile razy przyjdzie webhook, i tylko dla faktur tego WHMCS.
Zwroty
Zwracaj transakcję w WHMCS jak zwykle: moduł otworzy zwrot w Perly Pay w monecie, którą zapłacono (taką samą część — przy częściowym). Perly Pay poprosi klienta e-mailem o adres i go sprawdzi; Gateway Log powie, 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: dodaj adres callbacku jeszcze raz w trybie produkcyjnym i wklej jego sekret. - Dodaj adres https WHMCS w Sites that may embed the checkout w trybie produkcyjnym.
- Opłać jedną małą prawdziwą fakturę i ją zwróć.