Documentación de Integración: Checkout SDK - Botón de Pago

LASER Airlines

Versión del Documento: 1.0.0

1. Introducción

El SDK oficial de Laser Pago para el lado del cliente está diseñado para facilitar la integración de un botón de pago moderno y seguro en la plataforma web de LASER Airlines. Esta herramienta permite gestionar transacciones a través de Zelle y Pago Móvil, creando sesiones de pago y desplegando un modal de checkout de forma rápida, segura y estandarizada.

Esta documentación técnica establece los lineamientos para la implementación, asegurando que se cumplan los protocolos de prueba y el diseño basado en especificaciones (SDD) antes del paso a producción.

2. Requisitos Previos

• Entorno de ejecución compatible con Node.js.
• Credenciales de API (Clave Pública) emitidas por VILO TECHNOLOGIES, C.A.
• Conocimiento intermedio de TypeScript/JavaScript.

3. Instalación

Para integrar el paquete en el proyecto, ejecute los siguientes comandos a través de su entorno de terminal (ej. Windows PowerShell):

Usando npm:

npm install @laser-pagos/checkout

Usando yarn:

yarn add @laser-pagos/checkout

4. Arquitectura y Seguridad

Para mantener la integridad del sistema y cumplir con las normativas de auditoría técnica:

• Aislamiento de Entornos: Utilice el entorno sandbox para todas las fases de prueba y validación. Cambie a production únicamente tras superar los protocolos de testing obligatorios.
• Gestión de Claves: La publicKey puede residir en el frontend, pero la creación inicial de la sesión (sessionId) debe estar orquestada de forma segura para evitar manipulaciones en los parámetros de cobro. Se recomienda encarecidamente inyectar la clave mediante variables de entorno.

5. Guía de Integración Rápida

A continuación, se detalla la estructura estandarizada en TypeScript para manejar el ciclo de vida del pago.

import { Checkout, IPaymentResponse } from "@laser-pagos/checkout";

// Tu clave pública de Laser Pago. ¡No la expongas directamente en el frontend en producción!
// Es recomendable cargarla desde una variable de entorno.
const PUBLIC_KEY = "tu_clave_publica_aqui";

const handleCheckout = async () => {
  // 1. Inicializa el SDK con tu clave pública y el entorno deseado.
  const checkout = new Checkout({
    publicKey: PUBLIC_KEY,
    environment: "sandbox", // 'sandbox' para pruebas, 'production' para producción.
    lang: "es", // Opcional: 'es' o 'en' para los mensajes de error.
    fullScreen: false, // Opcional: true para abrir en pantalla completa.
  });

  try {
    // 2. Crea una sesión de pago desde tu backend.
    // Esta llamada devuelve un ID de sesión único.
    const sessionId = await checkout.createSession({
      type: "standard",
      locator: "ABCDEF",
      amount: 120.78,
      currency: "VES",
    });

    // 3. Si la sesión se creó con éxito, abre el modal de checkout.
    if (sessionId) {
      checkout.open({
        sessionId: sessionId,
        onSuccess: (payload: IPaymentResponse) => {
          console.log("¡Pago exitoso!", payload);
          // Aquí puedes redirigir al usuario a una página de éxito
          // o mostrarle una confirmación.
        },
        onError: (error: IPaymentResponse) => {
          console.error("Error en el pago:", error);
          // Muestra un mensaje de error al usuario.
        },
        onClose: () => {
          console.log("El modal de pago fue cerrado por el usuario.");
          // El usuario cerró el modal antes de completar el pago.
        },
      });
    }
  } catch (error) {
    console.error("Error al crear la sesión de Laser Pago:", error);
    // Maneja errores en la creación de la sesión (ej. problemas de red o API).
  }
};

// Llama a la función para iniciar el proceso de pago.
// handleCheckout();

6. Referencia de la API

6.1. Inicialización: new Checkout(config) o initCheckout(publicKey, options)

Constructor principal de la clase Checkout para instanciar el flujo de pago.

| Parámetro | Tipo | Requerido | Por Defecto | Descripción | | :------------ | :---------------------------- | :-------: | :---------- | :------------------------------------------------------------------------------ | | publicKey | string | ✅ Sí | - | Tu clave pública de API, solicitada a VILO TECHNOLOGIES. | | environment | 'sandbox' | 'production' | ❌ No | 'sandbox' | Define el entorno de despliegue y validación. | | lang | 'es' | 'en' | ❌ No | 'es' | Internacionalización de los mensajes del SDK. | | fullScreen | boolean | ❌ No | false | Determina si el renderizado ocupará toda la pantalla o se mantendrá como modal. |

6.2. Creación de Sesión: (CreateSessionParams)

Método asíncrono que registra la intención de pago en los servidores y retorna un identificador de sesión UUID (Promise<string>) con el sessionId.

| Parámetro | Tipo | Requerido | Por Defecto | Descripción | | :--------- | :------- | :-------: | :----------- | :--------------------------------------- | | amount | number | ✅ Sí | - | Monto exacto de la operación. | | currency | string | ✅ Sí | - | Moneda transaccional (VES, USD). | | locator | string | ✅ Sí | - | PNR o identificador único de la reserva. | | type | string | ❌ No | 'standard' | Modalidad de la sesión de pago. |

6.3. Apertura de Interfaz: checkout.open(options)

Desencadena el renderizado de la UI de pago para el usuario final, vinculada al sessionId previamente generado.

| Parámetro | Tipo | Requerido | Descripción | | :---------- | :--------- | :-------: | :----------------------------------------------------------------------------------------- | | sessionId | string | ✅ Sí | Identificador UUID obtenido de createSession. | | onSuccess | Function | ❌ No | Callback ejecutado tras la confirmación exitosa de los fondos. Retorna IPaymentResponse. | | onError | Function | ❌ No | Callback para manejo de rechazos o fallos de red. Retorna IPaymentResponse. | | onClose | Function | ❌ No | Callback disparado al cierre manual del modal por el usuario. |

7. Características Adicionales

7.1 Idiomas (Internacionalización)

Puedes configurar el idioma de los mensajes que emite el SDK (por ejemplo, en los callbacks de onError) usando la propiedad lang.

• Idiomas Soportados:
  • 'es' (Español) - Valor por defecto.
  • 'en' (Inglés).

7.2 Modos de Presentación

El SDK ofrece dos modos de visualización para el checkout, controlados por la opción fullScreen.

• Modo Modal (por defecto): fullScreen: false

  • El checkout se abre en una ventana modal superpuesta sobre tu contenido, con un sombreado de fondo. Es ideal para una experiencia integrada sin salir de la página actual.

• Modo Pantalla Completa: fullScreen: true

  • El checkout ocupa toda la ventana del navegador. Es útil para minimizar distracciones y centrar al usuario completamente en el proceso de pago.

8. Manejo de Errores

Si la creación de la sesión falla (por ejemplo, por una clave de API incorrecta, datos inválidos o problemas de red), el método lanzará un error. Es importante envolver la llamada en un bloque try...catch.

9. Soporte y Contacto

Para incidencias técnicas, reportes de vulnerabilidades o dudas durante el proceso de certificación, el equipo de desarrollo se encuentra a su disposición.

10. Licencia

Este proyecto está bajo la licencia MIT.

• Proveedor: VILO TECHNOLOGIES, C.A.
• Gestión de Documentación: Asegúrese de reflejar los cambios estructurales en su Software Design Documentation (SDD) interno.