Un componente Vue para gestionar pasarelas de pago.
npm install is-pasarela-component
is-pasarela-component te permite seleccionar dinámicamente qué workflow usar en tu aplicación (pago, cvc), manteniendo una interfaz unificada y fácil de integrar.
is-pasarela-component soporta diferentes workflows para adaptarse a las necesidades de tu aplicación. A continuación se describe cada uno:
tipoworkflow en el componente SwitcherPadre.vue:
SwitcherPadre.vue) que, según la prop tipoworkflow ('pago', 'cuenta', 'cvc', 'pagoefectivo'), decide qué flujo mostrar y qué pasarela de pago usar (Niubiz, Culqi, Izipay).
main.js (o de forma local) y ¡listo para usar!
pago-exitoso, error-pago, loaders, etc. directamente desde el componente usando @eventos, sin necesidad de librerías externas.
bash
npm install is-pasarela-component
`
---
⚠️ Compatible con Vue 2 y Vue 3
Funciona tanto en proyectos Vue 2 como Vue 3.
Creados con Vite, Vue CLI o cualquier build tool.
🧩 Registro del Componente
Una vez instalado, debes registrar el componente en tu aplicación.
Puedes hacerlo de forma global en tu main.js o de manera local en el componente donde lo usarás.
$3
`js
import { createApp } from "vue";
import App from "./App.vue";
import isPasarelaComponent from "is-pasarela-component"; // <-- Importa el paquete
const app = createApp(App);
// Registras con el nombre que quieras (ej: "is-pasarela-compoment")
app.component("is-pasarela-compoment", isPasarelaComponent);
app.mount("#app");
`
> En adelante, para invocarlo en tus templates, usarás la etiqueta (o el nombre que hayas asignado).
---
🧩 Props Disponibles
La siguiente tabla describe cada prop y sus valores por defecto. Puedes ajustarlos según tus necesidades:
---
$3
| Prop | Tipo | Requerido | Valor por Defecto | Descripción |
| -------------------- | --------- | --------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tipoworkflow | String | ✅ Sí | 'pago' | Determina qué flujo se muestra. Debe ser uno de: 'pago', 'cuenta', 'cvc', 'pagoefectivo' |
| sistema | String | ✅ Sí | 'TI_ADN' | Sistema que está usando el componente. |
| entorno | String | ✅ Sí | 'test' | Entorno de trabajo: 'test' o 'prod'. |
| producto | String | ✅ Sí | 'VIDAFREE' | Producto asociado al pago. |
| moneda | String | ✅ Sí | 'PEN' | Moneda del pago (PEN, USD, etc.). |
| config | Object | ❌ No | {} | Configuración unificada para todas las pasarelas. Solo se usa buttonColor. Ver sección Configuración por Pasarela. |
| cliente | Object | ✅ Sí | — | Información del cliente que será usada por la pasarela. Incluye: nombre, apellido, correo, documento, alias, telefono, direccion, ciudad, departamento, pais, codigoPostal, tipoDocumento, tokenId, numeroPropuesta, numeroPoliza, frecuenciaPago, firstPremium, esRecargo, tipoPago, placa, codigoComercio, delay, merchantBuyerId, transaccionId, estadoPropuesta, purchaseNumber, nroOrden, amount, ipNiubiz. |
| verCheckAfiliacion | Boolean | ✅ Sí | true | Muestra u oculta el checkbox de afiliación (para pagos recurrentes). |
| verTyC | Boolean | ✅ Sí | true | Muestra u oculta la sección de Términos y Condiciones. |
| textoBoton | String | ✅ Sí | 'PAGAR' | Texto del botón de pago (ej: "PAGAR Y AFILIAR"). |
| monedaBoton | String | ✅ Sí | 'S/' | Tipo de moneda mostrada en el botón (S/, $, USD, etc.). |
| montoBoton | String | ✅ Sí | '650.1' | Monto que se muestra en el botón. |
| logoPasarela | String | ❌ No | '' | URL o ruta local del logo que se mostrará en la parte inferior. |
---
$3
#### 💳 config
Tipo: Object • Requerido: No
Configuración unificada para todas las pasarelas. Actualmente solo se utiliza el campo buttonColor para personalizar el color del botón de pago.
Ejemplo de configuración:
`js
{
buttonColor: '#ff4081' // Color del botón de pago (hexadecimal)
}
`
> Nota: Aunque el objeto config puede contener otros campos como sessionkey, publicKey, tokenSesion, etc., estos son manejados internamente por el componente y se obtienen automáticamente del backend. Solo necesitas proporcionar el buttonColor si deseas personalizar la apariencia del botón.
---
📡 Eventos Emitidos
El componente emite eventos clave durante el flujo de pago. Puedes escucharlos directamente desde el componente usando la sintaxis de Vue: @nombre-del-evento="tuMetodo".
---
$3
Solicita mostrar un loader (por ejemplo, un spinner o modal de carga).
Payload:
N/A
---
$3
Indica que la carga finalizó y se puede ocultar el loader.
Payload:
N/A
---
$3
Solicita abrir la ventana o sección de Términos y Condiciones.
Payload:
N/A
---
$3
Emite si el usuario marca o desmarca el checkbox de afiliación.
Payload:
`js
{ checked: Boolean }
`
---
$3
Ocurre un error al cargar una librería externa (como el script de Culqi).
Payload:
Error o String con detalles
---
$3
Se emite cuando hay un error de validación o integración en el formulario (antes de enviar el pago).
Payload:
Error o Object con detalles
---
$3
Indica un error durante el procesamiento del pago a nivel de la pasarela.
Payload:
String u Object con detalle del error
---
$3
📌 Evento principal: notifica que el pago se completó exitosamente o no.
Payload:
Objeto con datos de la transacción (token, orden, monto, etc.)
---
$3
Se emite cuando el sistema de pasarelas se ha inicializado correctamente y está listo para procesar pagos.
Payload:
`js
{
pasarela: String, // Pasarela activa (NIUBIZ, CULQI, IZIPAY, PAGOEFECTIVO)
configuracion: Object, // Configuración específica de la pasarela
logo: String, // URL del logo de la pasarela
tipo: String, // Tipo de workflow ('pago', 'cuenta', 'cvc', 'pagoefectivo')
sistema: String, // Sistema que está usando el componente
entorno: String, // Entorno actual (test/prod)
producto: String // Producto asociado
}
`
---
$3
Se emite cuando ocurre un error durante la inicialización del sistema de pasarelas.
Payload:
`js
{
message: String, // Mensaje de error descriptivo
// ... otros campos del error según el tipo de fallo
}
`
---
$3
Se emite cuando un pago se ha completado exitosamente, diferenciándose del evento pago-exitoso por incluir información adicional sobre el flujo de afiliación.
Payload:
`js
{
statuscode: Number, // Código de estado HTTP
mensajecompleto: Object, // Respuesta completa del backend
codigo: String, // Código de respuesta de la pasarela
tipo: String, // Tipo de flujo ('invitacion-afiliacion' si no hay afiliación)
// ... otros campos según el tipo de respuesta
}
`
---
$3
Se emite cuando el sistema cambia automáticamente de una pasarela a otra (por ejemplo, cuando una pasarela falla y se activa la siguiente disponible).
Payload:
`js
{
pasarela: String, // Nueva pasarela activa
configuracion: Object, // Nueva configuración de la pasarela
logo: String // Logo de la nueva pasarela
}
`
---
$3
`vue
...
@pago-exitoso="onPagoExitoso"
@error-pago="onErrorPago"
@mostrar-loader="onMostrarLoader"
@ocultar-loader="onOcultarLoader"
@abrir-tyc="onAbrirTyC"
@ckeck-afiliar="onCheckAfiliar"
@error-libreria="onErrorLibreria"
@error-formulario="onErrorFormulario"
@sistema-inicializado="onSistemaInicializado"
@error-inicializacion="onErrorInicializacion"
@pago-completado-exitoso="onPagoCompletadoExitoso"
@pasarela-cambiada="onPasarelaCambiada"
/>
`
---
🛠️ Ejemplo Completo de Implementación
A continuación se muestra una implementación real y funcional del componente is-pasarela-component, incluyendo:
- Creación dinámica de sesiones
- Configuración de las tres pasarelas (Niubiz, Culqi, Izipay)
- Escucha de eventos clave
- Uso directo en el template
`vue
:tipoworkflow="tipoworkflow"
:sistema="sistema"
:entorno="entorno"
:producto="producto"
:moneda="moneda"
:config="config"
:cliente="cliente"
:verCheckAfiliacion="verCheckAfiliacion"
:verTyC="verTyC"
:textoBoton="textoBoton"
:monedaBoton="monedaBoton"
:montoBoton="montoBoton"
:logoPasarela="logoPasarela"
@mostrar-loader="onMostrarLoader"
@ocultar-loader="onOcultarLoader"
@ckeck-afiliar="onCheckAfiliar"
@abrir-tyc="onAbrirTyC"
@error-libreria="onErrorLibreria"
@error-formulario="onErrorFormulario"
@pago-exitoso="onPagoExitoso"
@error-pago="onErrorPago"
@sistema-inicializado="onSistemaInicializado"
@error-inicializacion="onErrorInicializacion"
@pago-completado-exitoso="onPagoCompletadoExitoso"
@pasarela-cambiada="onPasarelaCambiada"
/>
`
$3
Este ejemplo demuestra cómo integrar is-pasarela-component en una aplicación real, de forma clara y escalable.
#### 1️⃣ Determinación Automática de Pasarela
El componente determina automáticamente qué pasarela usar basándose en:
- Tipo de Workflow: El tipo de flujo ('pago', 'cuenta', 'cvc', 'pagoefectivo')
- Sistema: El sistema que está usando el componente (TI_ADN, etc.)
- Entorno: El entorno de trabajo (test o prod)
- Producto: El producto asociado (VIDAFREE, etc.)
- Moneda: La moneda del pago (PEN, USD, etc.)
No necesitas especificar manualmente qué pasarela usar - el componente lo hace automáticamente según la configuración del backend.
#### 2️⃣ Configuración Unificada
El componente utiliza una configuración unificada a través de la prop config:
- buttonColor: El único campo que necesitas especificar para personalizar la apariencia del botón de pago.
- Credenciales automáticas: Las credenciales específicas de cada pasarela (sessionkey, publicKey, tokenSesion, etc.) se obtienen y manejan automáticamente por el componente mediante servicios internos.
Esto simplifica significativamente la implementación, ya que no necesitas manejar diferentes estructuras de configuración para cada pasarela ni crear sesiones manualmente.
#### 3️⃣ Datos del Cliente
La prop cliente contiene información completa de la persona que está realizando el pago, incluyendo:
- Datos básicos: nombre, apellido, correo, documento, teléfono
- Dirección: dirección, ciudad, departamento, país, código postal
- Información específica: número de propuesta, número de póliza, frecuencia de pago, placa
- Configuración de pago: firstPremium, esRecargo, etc.
Estas propiedades son utilizadas por las pasarelas como metadatos y para llenar automáticamente los formularios.
#### 4️⃣ Eventos Emitidos
📡 Escucha los eventos del componente para reaccionar en tu lógica:
| Evento | Qué hace |
| --------------------------- | ------------------------------------------------------------- |
| @mostrar-loader | Muestra un spinner o animación de carga |
| @ocultar-loader | Oculta el loader cuando termina el proceso |
| @ckeck-afiliar | Captura si el usuario marcó el checkbox de afiliación |
| @abrir-tyc | Abre los Términos y Condiciones |
| @error-libreria | Error al cargar una librería externa (ej: Culqi) |
| @error-formulario | Error de validación o configuración |
| @pago-exitoso | ¡El pago fue exitoso! Ideal para redirigir o confirmar |
| @error-pago | Algo falló durante el pago, puedes mostrar un mensaje |
| @sistema-inicializado | Sistema listo para procesar pagos |
| @error-inicializacion | Error durante la inicialización del sistema |
| @pago-completado-exitoso | Pago completado con información de afiliación |
| @pasarela-cambiada | Notifica cuando cambia automáticamente de pasarela |
---
🖼️ Vista Previa de las Pasarelas
A continuación se muestran ejemplos visuales de cómo se renderiza cada pasarela integrada en el componente:
$3
---
$3
---
$3
🧠 A Tener en Cuenta
$3
1️⃣ Culqi inicia con el checkbox de afiliación desactivado.
El check de afiliación empieza desmarcado por defecto cuando se usa Culqi. Si deseas cambiar este comportamiento, asegúrate de ajustarlo manualmente.
2️⃣ Cada renderización requiere nuevas credenciales.
Cada vez que quieras cambiar, recargar o reutilizar una pasarela, debes generar nuevas credenciales con el servicio crear-sesion-pasarela.
Esto evita errores relacionados con sesiones expiradas o inválidas.
3️⃣ Tiempo de sesión sugerido: 5 minutos.
⌛ Se recomienda limitar el tiempo de sesión a 5 minutos en la vista donde se muestra el formulario.
Esto se debe a que algunas pasarelas (como Niubiz o Izipay) cierran su formulario por inactividad.
4️⃣ Las URL's de los servicios (autenticación, sesión, etc) pueden variar.
Estas URL dependen del entorno en el que estés trabajando (desarrollo, staging, producción).
Asegúrate de mantenerlas como variables de entorno o configuraciones externas para facilitar su mantenimiento y evitar exponer datos sensibles en el código fuente.
5️⃣ Evita renderizar el componente sin credenciales válidas.
Antes de mostrar el componente, asegúrate de haber obtenido correctamente la sesión correspondiente (session key, public key, token, etc).
Mostrarlo sin esta información puede causar errores o formularios en blanco.
6️⃣ Los montos deben coincidir en frontend y backend.
Verifica que el monto y moneda que se muestra en el botón coincida con el que se envía en la creación de sesión.
Esto evita rechazos por inconsistencias entre cliente y servidor.
7️⃣ No reutilices claves o tokens entre usuarios o sesiones.
Cada pago debe iniciar con credenciales únicas. Reutilizar tokens puede llevar a errores inesperados o incluso rechazos por parte de las pasarelas.
8️⃣ Compatibilidad Vue 2/Vue 3.
El componente está diseñado para funcionar en ambas versiones de Vue. La sintaxis de eventos y props es la misma, pero el registro del componente puede variar ligeramente entre versiones como se muestra en los ejemplos anteriores.
---
$3
✅ Configura correctamente tus llaves y credenciales en el backend.
🔒 Protege tokens y datos sensibles. No los expongas en el cliente.
🎨 Personaliza estilos y textos para mantener coherencia con tu marca o aplicación.
---
> 🧾 ¡Disfruta de tu integración de pagos con is-pasarela-component`!