Cómo instalar el módulo de pago de TAYPI en WHMCS

El módulo de pago WHMCS instalar de TAYPI permite a los comercios peruanos cobrar con QR interoperable directamente desde su sistema de facturación y soporte. En este tutorial paso a paso verás cómo instalarlo, configurar las credenciales de API y activar la pasarela para empezar a cobrar con QR.

¿Qué es el módulo de pago de TAYPI para WHMCS?

WHMCS es una de las plataformas más usadas por agencias de hosting, proveedores de SaaS y negocios digitales para gestionar clientes, facturación, soporte y cobros recurrentes. TAYPI, como pasarela de pagos con QR interoperable, ofrece un módulo oficial para WHMCS que conecta tu sistema con los pagos en tiempo real.

Cuando instalas y activas este módulo, cada factura o pedido puede generar un QR dinámico único con monto fijo y referencia. Ese QR expira en 15 minutos, por lo que no se puede reutilizar. El cliente paga desde Yape, Plin o cualquier billetera interoperable conectada a la CCE del BCRP. La confirmación del pago se verifica directamente con la entidad financiera, no con capturas de pantalla.

El módulo también usa webhooks en tiempo real y firmas HMAC-SHA256 para que WHMCS marque automáticamente una factura como pagada cuando TAYPI confirma la transacción. Esto elimina la validación manual y reduce los errores operativos.

Una ventaja importante de esta integración es que TAYPI no procesa tarjetas de crédito ni débito, solo billeteras y QR interoperable. Eso significa cero contracargos y sin comisiones de marca de tarjetas. Si tu negocio ya usa pago con QR o quieres empezar a aceptarlo, este módulo es una vía práctica para automatizar los cobros.

Requisitos para instalar el módulo de pago WHMCS

Antes de comenzar con la instalación, asegúrate de cumplir estos puntos:

• Tener una instalación de WHMCS activa y con acceso al panel de administración.
• Contar con una cuenta TAYPI verificada. Puedes crearla gratis en app.taypi.pe/register.
• Tener a la mano las credenciales de API: clave pública, clave privada y clave de sandbox para pruebas.
• Acceso al servidor o al administrador de archivos para subir el módulo.
• Un dominio con certificado SSL válido (HTTPS) para que los webhooks y las notificaciones funcionen correctamente.
• Revisar la documentación para developers de TAYPI para conocer los endpoints disponibles.

Una integración típica toma alrededor de un día, siempre que ya tengas la cuenta TAYPI activa y los accesos a WHMCS listos. No necesitas ser un programador experto, pero sí conviene tener nociones básicas de administración de módulos y pasarelas.

Paso 1: Instalar el módulo de pago WHMCS de TAYPI

El primer paso es subir los archivos del módulo a tu instalación de WHMCS. El flujo general es el siguiente:

1. Descarga el módulo oficial de TAYPI desde tu panel de comercio o desde la documentación para developers.
2. Sube la carpeta del módulo a la ubicación de pasarelas de pago de tu WHMCS (por lo general, la carpeta de módulos de pago).
3. Verifica que los archivos hayan quedado correctamente alojados en el servidor.
4. Accede al panel de administración de WHMCS y busca la sección de pasarelas de pago o módulos de pago.
5. Localiza a TAYPI en la lista de pasarelas disponibles y actívalo.

No necesitas modificar el código fuente de WHMCS. El módulo está diseñado para integrarse de manera estándar con la estructura de pasarelas de pago de la plataforma. Si tienes dudas sobre la ruta exacta, la documentación incluida en el módulo te indicará la ubicación recomendada.

Una vez activado, verás los campos de configuración donde deberás ingresar las credenciales de API.

Paso 2: Configurar credenciales de API y ajustes de cobro

Después de activar el módulo, llega la parte más importante: conectar tu cuenta TAYPI con WHMCS.

En la pantalla de configuración del módulo deberás completar:

• Clave de API de producción: identifica tu cuenta para transacciones reales.
• Clave de API de sandbox: permite probar sin mover dinero real.
• Secreto para firma HMAC-SHA256: se usa para validar la integridad de las notificaciones.
• URL de webhook: la URL que TAYPI usará para avisarle a WHMCS cuando un pago se confirme.
• Entorno a utilizar: sandbox para pruebas o producción para cobros reales.

La autenticación de TAYPI usa firma HMAC-SHA256 e idempotencia. La idempotencia evita que un mismo cobro se procese dos veces, incluso si el webhook se reenvía o el cliente intenta pagar nuevamente. Si quieres profundizar en cómo verificar estas firmas en tu backend, revisa esta guía para verificar firmas HMAC-SHA256.

También puedes mapear los estados de pago según la lógica de tu negocio. Por ejemplo, cuando TAYPI devuelva un estado “confirmado”, WHMCS debería marcar la factura como pagada. Si el QR expira o el pago falla, la factura puede quedar en estado pendiente o cancelado.

En este punto conviene revisar la documentación de seguridad de TAYPI para entender cómo se protegen los datos y por qué el cifrado TLS 1.3 y las firmas HMAC son relevantes para tu integración.

Paso 3: Probar el módulo en sandbox y activar producción

Antes de recibir pagos reales, prueba el módulo en modo sandbox. TAYPI ofrece claves de prueba que simulan todo el flujo de pago sin transferir dinero.

Te recomiendo seguir este orden:

1. Configura el módulo con las claves de sandbox.
2. Genera una factura de prueba en WHMCS.
3. Abre el QR de pago o el enlace de checkout.
4. Simula el pago desde una billetera de prueba.
5. Verifica que WHMCS reciba el webhook en tiempo real y marque la factura como pagada.
6. Revisa que el monto, la referencia y el estado sean correctos.

Cuando las pruebas salgan bien, cambia las credenciales a producción, actualiza la URL del webhook si es necesario y realiza una transacción real de monto bajo para confirmar que todo funciona en el entorno real. Para entender mejor cómo funcionan las notificaciones automáticas, consulta la guía completa de webhooks de pagos en tiempo real.

Una vez en producción, cada cobro generará un QR dinámico único que expira en 15 minutos. Si el cliente no paga dentro de ese plazo, el QR deja de ser válido y se debe generar uno nuevo.

Buenas prácticas al usar el módulo de pago con QR

Para sacarle el máximo provecho al módulo de TAYPI en WHMCS, ten en cuenta estas recomendaciones:

• Mantén las claves seguras: nunca compartas tu secreto HMAC ni lo subas a repositorios públicos.
• Usa siempre HTTPS: los webhooks viajan por internet y deben ir cifrados.
• Monitorea los webhooks: revisa que WHMCS esté respondiendo correctamente a las notificaciones de TAYPI.
• Aprovecha la conciliación automática: cada cobro queda asociado a su referencia, lo que facilita cuadrar la contabilidad.
• Configura los reintentos de pago: si un cliente no paga, puedes enviar una nueva factura con un QR nuevo.
• Considera activar Yape On File: con el pago en un clic, tus clientes afilian su Yape una sola vez y luego pagan sin escanear QR, ideal para suscripciones o cobros recurrentes.

Diferencias entre sandbox y producción

| Característica | Sandbox | Producción | |