🧾 is-pasarela-component

💳 Un componente Vue 2/3 para integrar Niubiz, Culqi e Izipay en una sola interfaz

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.

🧭 Descripción de los Workflows

El componente is-pasarela-component soporta diferentes workflows para adaptarse a las necesidades de tu aplicación. A continuación se describe cada uno:

💳 Workflow "pago"

Permite realizar pagos tradicionales con tarjeta a través de las pasarelas Niubiz, Culqi o Izipay.

• Muestra el formulario de pago correspondiente según la pasarela con prioridad 1 configurada en el sistema.
• Gestiona la autenticación, la sesión y la validación del pago.
• Ideal para cobros únicos o compras en línea.

🔒 Workflow "cvc"

Permite la validación del código CVC para afiliar una tarjeta a un servicio de recurrencia o débito automático.

• Solicita únicamente el CVC para asociar la tarjeta a pagos recurrentes o débitos automáticos.
• Es fundamental para completar el proceso de afiliación de la tarjeta y habilitar cobros automáticos en el futuro.

Puedes seleccionar el workflow deseado usando la prop tipoworkflow en el componente SwitcherPadre.vue:

✅ Ahorra tiempo y evita duplicar formularios.
🧠 Centraliza la lógica de cada pasarela (Niubiz, Culqi, Izipay).
🎯 Ideal para aplicaciones Vue 2 y Vue 3 que requieran múltiples opciones de pago.

✨ Características Principales

• 🔀 Switcher Padre: Un componente central (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).

• ⚙️ Props de Configuración: Cada pasarela tiene su propio objeto de configuración para que puedas pasar tus keys, valores personalizados y parámetros específicos.

• 🧩 Integración Simple: Solo necesitas importar el componente, registrarlo en tu main.js (o de forma local) y ¡listo para usar!

• 📡 Eventos Reactivos: Captura eventos clave como pago-exitoso, error-pago, loaders, etc. directamente desde el componente usando @eventos, sin necesidad de librerías externas.

📚 Tabla de Contenidos

1. 📦 Instalación
2. 🧩 Registro del Componente
3. 🧩 Props Disponibles
4. 📡 Eventos Emitidos
5. 🛠️ Ejemplo Completo de Implementación
6. 🖼️ Vista Previa de las Pasarelas
7. 🧠 A tener en cuenta

📦 Instalación

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.

🌐 Registro Global Vue 3 (ejemplo en main.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 <is-pasarela-compoment /> (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:

🎯 Propiedades Principales

| 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. |

⚙️ Configuración por Pasarela

💳 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:

{
  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".

🌀 mostrar-loader

Solicita mostrar un loader (por ejemplo, un spinner o modal de carga).

Payload:
N/A

✅ ocultar-loader

Indica que la carga finalizó y se puede ocultar el loader.

Payload:
N/A

📜 abrir-tyc

Solicita abrir la ventana o sección de Términos y Condiciones.

Payload:
N/A

📝 ckeck-afiliar

Emite si el usuario marca o desmarca el checkbox de afiliación.

Payload:

{ checked: Boolean }

❌ error-libreria

Ocurre un error al cargar una librería externa (como el script de Culqi).

Payload: Error o String con detalles

🛑 error-formulario

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

⚠️ error-pago

Indica un error durante el procesamiento del pago a nivel de la pasarela.

Payload:
String u Object con detalle del error

🎉 pago-exitoso

📌 Evento principal: notifica que el pago se completó exitosamente o no.

Payload:
Objeto con datos de la transacción (token, orden, monto, etc.)

🚀 sistema-inicializado

Se emite cuando el sistema de pasarelas se ha inicializado correctamente y está listo para procesar pagos.

Payload:

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

❌ error-inicializacion

Se emite cuando ocurre un error durante la inicialización del sistema de pasarelas.

Payload:

{
  message: String,       // Mensaje de error descriptivo
  // ... otros campos del error según el tipo de fallo
}

✅ pago-completado-exitoso

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:

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

🔄 pasarela-cambiada

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:

{
  pasarela: String,      // Nueva pasarela activa
  configuracion: Object, // Nueva configuración de la pasarela
  logo: String          // Logo de la nueva pasarela
}

🦻Cómo escuchar los eventos

<template>
<is-pasarela-component
  ...
  @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"
/>
</template>
<script>
...
methods: {
  onPagoExitoso(data) {
    console.log("Pago exitoso:", data);
  },
  onErrorPago(error) {
    console.error("Error en el pago:", error);
  },
  onSistemaInicializado(data) {
    console.log("Sistema inicializado:", data);
    // Aquí puedes actualizar el estado de tu aplicación
    // con la información de la pasarela activa
  },
  onErrorInicializacion(error) {
    console.error("Error de inicialización:", error);
    // Manejar errores de inicialización del sistema
  },
  onPagoCompletadoExitoso(data) {
    console.log("Pago completado exitosamente:", data);
    // Manejar el flujo post-pago (afiliación, redirección, etc.)
  },
  onPasarelaCambiada(data) {
    console.log("Pasarela cambiada a:", data.pasarela);
    // Actualizar la UI cuando cambie la pasarela automáticamente
  },
  // ...otros handlers
}
...
</script>

🛠️ 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

<template>
  <div v-if="render">
    <is-pasarela-component
      :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"
    />
  </div>
</template>

<script>
import isPasarelaComponent from "is-pasarela-component";

//Los logotipos son opcionales
import culqiLogo from "@/assets/culqi_logo.png";
import niubizLogo from "@/assets/niubiz_logo.png";
import izipayLogo from "@/assets/izipay_logo.png";

export default {
  components: { isPasarelaComponent },
  data() {
    return {
      render: false,
      
      // Configuración del workflow y sistema
      tipoworkflow: 'pago',
      sistema: 'TI_ADN',
      entorno: 'test', // 'test' o 'prod'
      producto: 'VIDAFREE',
      moneda: 'PEN',
      
      // Configuración unificada - solo necesitas el color del botón
      config: {
        buttonColor: '#ff4081'
      },
      // Información del cliente
      cliente: {
        nombre: 'MIGUEL ANGEL',
        apellido: 'QUISPE',
        correo: '[email protected]',
        documento: '71755734',
        alias: 'MIGUEL ANGEL',
        telefono: '930248757',
        direccion: 'Av. Lima 123',
        ciudad: 'Lima',
        departamento: 'Lima',
        pais: 'PE',
        codigoPostal: '00001',
        tipoDocumento: 'DNI',
        numeroPropuesta: '08456879879',
        numeroPoliza: '75402136544',
        frecuenciaPago: 'MENSUAL',
        placa: 'ABC123',
        firstPremium: true,
        esRecargo: false
      },
      // Configuración de la interfaz
      verCheckAfiliacion: true,
      verTyC: true,
      textoBoton: 'PAGAR',
      monedaBoton: 'S/',
      montoBoton: '650.1',
      logoPasarela: null
    };
  },
  async mounted() {
    // El componente se inicializa automáticamente
    // No necesitas crear sesiones manualmente
    this.render = true;
  },
  methods: {
    onMostrarLoader() {
      console.log("mostrar-loader");
    },
    onOcultarLoader() {
      console.log("ocultar-loader");
    },
    onCheckAfiliar(data) {
      console.log("ckeck-afiliar", data);
    },
    onAbrirTyC() {
      console.log("abrir-tyc");
    },
    onErrorLibreria(err) {
      console.log("error-libreria", err);
    },
    onErrorFormulario(err) {
      console.log("error-formulario", err);
    },
    onPagoExitoso(data) {
      console.log("pago-exitoso", data);
      alert(`¡Pago Exitoso! ID: ${data.id || data.transactionToken}`);
    },
    onErrorPago(err) {
      console.log("error-pago", err);
      alert("Ocurrió un error al procesar tu pago. Intenta nuevamente.");
    },
    onSistemaInicializado(data) {
      console.log("Sistema inicializado:", data);
      // Aquí puedes actualizar el estado de tu aplicación
      // con la información de la pasarela activa
      this.logoPasarela = this.obtenerLogoPasarela(data.pasarela);
    },
    onErrorInicializacion(error) {
      console.error("Error de inicialización:", error);
      alert("Error al inicializar el sistema de pagos. Intenta recargar la página.");
    },
    onPagoCompletadoExitoso(data) {
      console.log("Pago completado exitosamente:", data);
      // Manejar el flujo post-pago (afiliación, redirección, etc.)
      if (data.tipo === 'invitacion-afiliacion') {
        alert("Pago exitoso. Te invitamos a afiliar tu tarjeta para futuros pagos.");
      } else {
        alert("¡Pago y afiliación completados exitosamente!");
      }
    },
    onPasarelaCambiada(data) {
      console.log("Pasarela cambiada a:", data.pasarela);
      // Actualizar la UI cuando cambie la pasarela automáticamente
      this.logoPasarela = this.obtenerLogoPasarela(data.pasarela);
      alert(`Se cambió automáticamente a la pasarela: ${data.pasarela}`);
    },
    obtenerLogoPasarela(pasarela) {
      switch(pasarela) {
        case 'NIUBIZ': return niubizLogo;
        case 'CULQI': return culqiLogo;
        case 'IZIPAY': return izipayLogo;
        default: return null;
      }
    }
  }
};
</script>

🧩 Explicación del Ejemplo

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:

🔵 Formulario Niubiz

🟠 Formulario Culqi

🔴 Formulario Izipay

🧠 A Tener en Cuenta

⚠️ Consideraciones Generales

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.

🔐 Buenas Prácticas para Producción

✅ 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!
Si tienes dudas o sugerencias, no dudes en contribuir o abrir un issue 🐛