# 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](https://pay.perly.io/docs/sdks.md) ya viene dentro.

> **Nota:** Perly Pay factura en USD o EUR. Para clientes con otra moneda, elige USD o EUR en **Convert To For Processing** de la pasarela; el pago se registra igualmente en la moneda de la propia factura. Sin esto, esos clientes verán una indicación para elegir otro método de pago.

## Instalación

1. **Consigue el zip** — El módulo está en camino a WHMCS Marketplace. Mientras no esté, [escríbenos](https://pay.perly.io/es/contact) 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.php` y `modules/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](https://pay.perly.io/docs/test-mode.md), `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:

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

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