# WHMCS

> Gateway di pagamento per WHMCS: i clienti pagano le fatture in bitcoin o USDC/USDT dritto nel tuo wallet, e un webhook firmato registra il pagamento.

Il modulo Perly Pay aggiunge le crypto alle fatture di WHMCS. Il cliente preme **Pay with crypto**; il saldo della fattura diventa una fattura Perly Pay, pagata sopra la pagina di WHMCS o su una pagina a parte; un webhook firmato registra il pagamento in WHMCS. WHMCS 8, PHP 8.1+ con curl. Niente da installare con Composer: l’[SDK PHP](https://pay.perly.io/docs/sdks.md) è già incluso.

> **Nota:** Perly Pay fattura in USD o EUR. Per i clienti in un’altra valuta, scegli USD o EUR in **Convert To For Processing** del gateway; il pagamento viene comunque registrato nella valuta della fattura stessa. Senza questo, quei clienti vedranno un invito a scegliere un altro metodo di pagamento.

## Installazione

1. **Prendi lo zip** — Il modulo è in arrivo su WHMCS Marketplace. Finché non c’è, [scrivici](https://pay.perly.io/it/contact) per avere `perly-pay-whmcs.zip`.
2. **Caricalo** — Estrailo sopra la tua cartella di WHMCS. Si aggiungono `modules/gateways/perlypay.php`, `modules/gateways/callback/perlypay.php` e `modules/gateways/perlypay/`.
3. **Attivalo** — Configuration → Apps & Integrations → Payment Gateways (o Setup → Payment Gateways), attiva **Perly Pay**.

## Configurazione

| Campo | Cosa inserire |
| --- | --- |
| Secret key | Dashboard → Developers → API keys. `sk_test_…` per la [modalità test](https://pay.perly.io/docs/test-mode.md), `sk_live_…` per il denaro reale. |
| Webhook signing secret | `whsec_…`, dal webhook che aggiungerai per questo WHMCS (qui sotto). |
| Payment page | **Overlay** apre il checkout sopra la fattura (pay.js). **Redirect** porta il cliente alla sua pagina. Sui telefoni si apre sempre la pagina. |
| Currencies | USD ed EUR, o solo una delle due. |

1. **Incolla la chiave** — Salva e premi **Test connection** nel campo della chiave: vedrai se la chiave funziona, la sua modalità e se Perly Pay ha il webhook di questo WHMCS.
2. **Aggiungi il webhook** — In Dashboard → Developers → Webhooks, aggiungi l’indirizzo della configurazione, `https://your-whmcs/modules/gateways/callback/perlypay.php`, con gli eventi di fatture e rimborsi. Incolla il suo segreto e salva.
3. **Consenti l’overlay** — In Dashboard → Settings, aggiungi l’indirizzo del tuo WHMCS in **Sites that may embed the checkout**. Senza questo, l’overlay propone di aprire il checkout in una nuova scheda.

## Provalo

Con una chiave `sk_test_…`, apri una fattura non pagata nell’area clienti e premi **Pay with crypto**. Paga con monete di test o via API; l’id della fattura è nel checkout:

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

In pochi secondi la fattura di WHMCS diventa **Paid**. Billing → Gateway Log mostra la rete, l’importo e un link alla transazione.

## Come le fatture seguono i pagamenti

| In Perly Pay | In WHMCS |
| --- | --- |
| Pagata, mittente controllato (`invoice.fulfilled`) | Un pagamento per l’importo fatturato al cliente, nella valuta della fattura, con l’id di pagamento Perly Pay (`pay_…`). WHMCS segna la fattura come Paid e fa il resto come sempre. |
| Vista, pagata in parte, pagata e ancora in verifica | Una riga nel Gateway Log. Nessun pagamento. |
| Trattenuta per [verifica](https://pay.perly.io/docs/screening.md) | Una riga nel Gateway Log con il motivo. Decidi in Perly Pay. |
| Scaduta o annullata | Una riga nel Gateway Log. Premere di nuovo il pulsante crea una nuova fattura. |
| Rimborso aperto, pronto, inviato, confermato | Una riga nel Gateway Log: cosa inviare e dove. |

Premere di nuovo il pulsante riusa la fattura aperta finché il saldo è lo stesso. Ogni pagamento viene registrato una sola volta, per quante volte arrivi il webhook, e solo per le fatture di questo WHMCS.

## Rimborsi

Rimborsa la transazione in WHMCS come sempre: il modulo apre un [rimborso](https://pay.perly.io/docs/refunds.md) in Perly Pay nella moneta con cui si è pagato (la stessa proporzione se è parziale). Perly Pay chiede al cliente un indirizzo via email e lo controlla; il Gateway Log ti dice cosa inviare e dove. Lo invii dal tuo wallet e incolli l’id della transazione in Perly Pay: Perly Pay non tiene mai il denaro.

## Andare live

- Attiva la modalità live in Perly Pay e collega le chiavi pubbliche del tuo wallet.
- Incolla una chiave `sk_live_…`. Chiavi e webhook live sono separati da quelli di test: aggiungi di nuovo l’indirizzo di ritorno in modalità live e incolla il suo segreto.
- Aggiungi l’indirizzo https del tuo WHMCS in **Sites that may embed the checkout** in modalità live.
- Paga una piccola fattura reale e rimborsala.