Guías
WHMCS
Pasarela de pago para WHMCS: los clientes pagan sus facturas en bitcoin o USDC/USDT directo a tu billetera, y un webhook firmado registra el pago.
El módulo de Perly Pay añade cripto a las facturas de WHMCS. El cliente pulsa Pagar con cripto; el saldo de la factura se convierte en una factura de Perly Pay, que se paga sobre la página de WHMCS o en una página aparte; un webhook firmado registra el pago en WHMCS. WHMCS 8, PHP 8.1+ con curl. No hace falta instalar nada con Composer: el SDK de PHP ya viene dentro.
Instalación
- 1
Consigue el zip
El módulo está en camino a WHMCS Marketplace. Mientras no esté, escríbenos para pedir
perly-pay-whmcs.zip. - 2
Súbelo
Descomprímelo sobre tu carpeta de WHMCS. Se añaden
modules/gateways/perlypay.php,modules/gateways/callback/perlypay.phpymodules/gateways/perlypay/. - 3
Actívalo
Configuration → Apps & Integrations → Payment Gateways (o Setup → Payment Gateways), activa Perly Pay.
Configuración
| Campo | Qué poner |
|---|---|
| Clave secreta | Dashboard → Developers → API keys. sk_test_… para el modo de prueba, sk_live_… para dinero real. |
| Secreto de firma del webhook | whsec_…, del webhook que añadirás para este WHMCS (abajo). |
| Página de pago | Superpuesta abre el pago sobre la factura (pay.js). Redirección lleva al cliente a su página. En móviles siempre se abre la página. |
| Monedas | USD y EUR, o solo una. |
- 1
Pega la clave
Guarda y pulsa Probar conexión en el campo de la clave: verás si la clave funciona, su modo y si Perly Pay tiene el webhook de este WHMCS.
- 2
Añade el webhook
En Dashboard → Developers → Webhooks, añade la dirección de la configuración,
https://your-whmcs/modules/gateways/callback/perlypay.php, con los eventos de facturas y reembolsos. Pega su secreto y guarda. - 3
Permite la superposición
En Dashboard → Settings, añade la dirección de tu WHMCS en Sites that may embed the checkout. Sin esto, la superposición ofrece abrir el pago en una pestaña nueva.
Pruébalo
Con una clave sk_test_…, abre una factura sin pagar en el área de cliente y pulsa Pagar con cripto. Paga con monedas de prueba o por la API; el id de la factura está en la página de pago:
En unos segundos, la factura de WHMCS pasa a Paid. Billing → Gateway Log muestra la red, el importe y un enlace a la transacción.
Cómo las facturas siguen los pagos
| En Perly Pay | En WHMCS |
|---|---|
Pagada, remitente revisado (invoice.fulfilled) | Un pago por el importe facturado al cliente, en la moneda de la factura, con el id de pago de Perly Pay (pay_…). WHMCS marca la factura como Paid y hace el resto como siempre. |
| Vista, pagada en parte, pagada y aún en revisión | Una línea en Gateway Log. Sin pago. |
| Retenida para revisión | Una línea en Gateway Log con el motivo. Decide en Perly Pay. |
| Caducada o cancelada | Una línea en Gateway Log. Pulsar el botón otra vez crea una factura nueva. |
| Reembolso abierto, listo, enviado, confirmado | Una línea en Gateway Log: qué enviar y adónde. |
Pulsar el botón otra vez reutiliza la factura abierta mientras el saldo sea el mismo. Cada pago se registra una sola vez, llegue el webhook las veces que llegue, y solo para facturas de este WHMCS.
Reembolsos
Reembolsa la transacción en WHMCS como siempre: el módulo abre un reembolso en Perly Pay en la moneda con que se pagó (la misma proporción si es parcial). Perly Pay pide al cliente una dirección por correo y la revisa; Gateway Log te dice qué enviar y adónde. Lo envías desde tu billetera y pegas el id de la transacción en Perly Pay: Perly Pay nunca guarda el dinero.
Pasar a real
- Activa el modo real en Perly Pay y conecta las claves públicas de tu billetera.
- Pega una clave
sk_live_…. Las claves y los webhooks reales van aparte de los de prueba: añade otra vez la dirección de retorno en modo real y pega su secreto. - Añade la dirección https de tu WHMCS en Sites that may embed the checkout en modo real.
- Paga una factura real pequeña y reembólsala.