Guide
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 è già incluso.
Installazione
- 1
Prendi lo zip
Il modulo è in arrivo su WHMCS Marketplace. Finché non c’è, scrivici 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.phpemodules/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, 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:
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 | 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 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.