# 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](https://pay.perly.io/docs/sdks.md) jest już w środku.

> **Uwaga:** Perly Pay wystawia faktury w USD lub EUR. Dla klientów z inną walutą wybierz w bramce **Convert To For Processing** USD lub EUR; płatność i tak zapisze się w walucie samej faktury. Bez tego tacy klienci zobaczą wskazówkę, by wybrać inną metodę płatności.

## Instalacja

1. **Zdobądź zip** — Moduł jest już w drodze do WHMCS Marketplace. Dopóki go tam nie ma, [napisz do nas](https://pay.perly.io/pl/contact) po `perly-pay-whmcs.zip`.
2. **Wgraj** — Rozpakuj go na katalog WHMCS. Dojdą `modules/gateways/perlypay.php`, `modules/gateways/callback/perlypay.php` i `modules/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](https://pay.perly.io/docs/test-mode.md), `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:

```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 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](https://pay.perly.io/docs/screening.md) | 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](https://pay.perly.io/docs/refunds.md) 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óć.