Plugins de e-commerce
Gateway de WHMCS
Instala y configura el gateway oficial de WHMCS con OAuth nativo, checkout alojado MakePay y callbacks firmados.
Gateway MakePay para WHMCS
Resumen
El gateway oficial MakePay para WHMCS agrega checkout cripto alojado a facturas WHMCS. WHMCS renderiza un botón de pago en la factura, MakePay crea el enlace de pago alojado y el callback firmado marca la factura como pagada después de que el pago se liquida.
Usa Connect MakePay para configuración normal. Las credenciales manuales con clave API siguen disponibles como fallback.
Antes de empezar
- WHMCS 8.13 LTS o WHMCS 9.x
- PHP 8.1 o superior con OpenSSL habilitado
- WHMCS System URL en HTTPS
- Acceso administrador WHMCS a Payment Gateways
- Una empresa MakePay donde puedas gestionar ajustes de pago
Instalar el gateway
Descarga el paquete ZIP más reciente:
https://plugins.makecrypto.io/downloads/whmcs/latest.zip
Extrae el ZIP y sube el directorio modules a la raíz de WHMCS. El paquete instala estos archivos:
modules/gateways/makepay.php
modules/gateways/makepay/checkout.php
modules/gateways/makepay/oauth.php
modules/gateways/makepay/lib/*.php
modules/gateways/callback/makepay.php
En WHMCS, abre System Settings > Payment Gateways, activa MakePay y guarda los ajustes del gateway.
Conectar MakePay
Abre los ajustes del gateway MakePay y elige Connect MakePay. El gateway:
- Abre MakeCrypto en una pestaña del navegador.
- Te pide iniciar sesión y elegir la empresa que recibirá los pagos.
- Muestra los permisos que necesita el gateway WHMCS.
- Te devuelve a WHMCS tras aprobar.
- Guarda la conexión en los ajustes del gateway WHMCS.
- Configura la URL de callback MakePay y el secreto de webhook.
Configurar MakePay
Después de conectar, conserva Connection method en el modo conectado predeterminado. Revisa:
- ID de empresa MakePay
- Activo de liquidación
- Expiración de pago
- Estado de conexión MakePay
- Secreto de firma de webhook
El fallback manual requiere ID de empresa MakePay, ID de clave API, secreto de clave API y secreto de webhook.
Flujo de checkout
Cuando un cliente abre una factura WHMCS impaga, el gateway MakePay renderiza un botón de pago. El handler de checkout valida el payload de formulario firmado, carga la factura mediante helpers de API local de WHMCS, crea un enlace de pago MakePay y redirige al cliente al checkout alojado MakePay.
| Campo | Propósito |
|---|---|
source=whmcs | Identifica la integración |
orderId=whmcs_invoice_<invoiceId> | Mapea actividad MakePay de vuelta a WHMCS |
invoiceId | ID de factura WHMCS |
clientId | ID de cliente WHMCS |
moduleVersion | Versión instalada del gateway MakePay |
whmcsVersion | Versión runtime de WHMCS |
El comprador vuelve a la factura WHMCS original después del pago o cancelación.
Estados de factura
MakePay envía callbacks firmados a:
https://billing.example.com/modules/gateways/callback/makepay.php
| Estado MakePay | Comportamiento de WHMCS |
|---|---|
paid, completed, confirmed, succeeded | Llama addInvoicePayment y registra el ID de transacción |
failed, expired | Registra el callback y deja la factura impaga |
cancelled, canceled | Registra el callback y deja la factura impaga |
refunded | Registra el callback para revisión manual |
| Otros estados | Se registran y se ignoran |
Los logs de transacción WHMCS incluyen el payload de callback MakePay para que los equipos de soporte puedan rastrear UID de pago, metadata de factura, importe y estado.
Notas de seguridad
El gateway guarda detalles de conexión en los ajustes de gateway de WHMCS. Limita el acceso administrador de WHMCS a operadores confiables y desconecta el gateway en MakeCrypto si una cuenta administradora o backup del servidor queda expuesto.
La conexión solicita estos permisos:
company:readmakepay:payment-links:readmakepay:payment-links:writemakepay:customers:readmakepay:customers:writemakepay:settings:readmakepay:settings:write
Solución de problemas
Si Connect MakePay no puede iniciar, confirma que WHMCS System URL sea HTTPS y coincida con el dominio público de facturación. Si los clientes ven un error de checkout, confirma que el gateway esté activo, la factura esté impaga y el ID de empresa MakePay esté guardado. Si los callbacks no marcan facturas como pagadas, compara la URL de callback MakePay con la URL de callback WHMCS anterior y rota el secreto de webhook desde los ajustes del gateway.