Integración de Aplicación Web

Esta página cubre los dos enfoques de integración del lado del cliente para el contrato Web & SDK: redirigir al usuario a un recorrido alojado por Unico, e incorporar el recorrido mediante el SDK de iFrame.

Redirigir al usuario

Después de crear un proceso, la respuesta incluye una URL que apunta al recorrido alojado por Unico. Utiliza esta URL para transferir al usuario a la experiencia de captura. Hay dos formas de gestionar esta transición:

1. Redirección estándar

Redirige al usuario directamente a la URL del recorrido. Cuando el usuario completa el proceso, Unico lo redirige de vuelta a la URL que especificaste durante la creación del proceso.

2. Nueva pestaña con window.open()

Abre el recorrido en una nueva pestaña del navegador para que el usuario permanezca en un contexto separado. Monitorea el cambio de URL hacia tu URL de retorno y cierra la pestaña cuando el proceso esté completo.

Para más detalles sobre la API window.open(), consulta la documentación de MDN.

iFrame

advertencia

Las integraciones que no siguen los estándares de esta documentación pueden causar interrupciones inesperadas y no estarán cubiertas por el soporte de Unico.

Ejemplos de enfoques no compatibles: incorporar el SDK dentro de un WebView, o cargar el iFrame directamente mediante una etiqueta HTML.

Cómo comenzar

Paso 1 — Instalación

El SDK de by Unico utiliza el mismo paquete que IDPay:

npm install idpay-b2b-sdk

consejo

Instala sin fijar una versión específica para que tu gestor de paquetes siempre descargue automáticamente las últimas versiones menores y de parche.

Antes de comenzar, registra tus dominios con el equipo de soporte de Unico. Todos los dominios deben usar HTTPS.

Paso 2 — Llama a init(options)

Inicializa el SDK y precarga los recursos, creando una experiencia más fluida para el usuario final. Llama a esto lo antes posible en tu flujo.

Parámetro	Requerido	Descripción
type	Sí	Establece en 'IFRAME' para los flujos de by Unico
token	Sí	Token del proceso devuelto por la API de Creación de Proceso
env	No	Establece en 'uat' solo para entornos de prueba

import { ByUnicoSDK } from "idpay-b2b-sdk";

ByUnicoSDK.init({
  type: 'IFRAME',
  token,
  // env: 'uat' // only for test environments
});

Paso 3 — Llama a open(options)

Muestra el iFrame precargado e inicia el flujo de mensajes entre tu página y el recorrido de Unico.

Parámetro	Requerido	Descripción
transactionId	Sí	ID del proceso devuelto por la API de Creación de Proceso
token	Sí	Token del proceso devuelto por la API de Creación de Proceso
onFinish	Sí	Callback ejecutado cuando el recorrido finaliza o se cierra

El callback onFinish recibe un objeto de proceso con el ID de transacción, una URL de redirección y el tipo de finalización.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: (process) => {
    console.log('Process finished', process);
    // process.transaction.redirectUrl — use this to navigate the user
  },
});

// To close the SDK explicitly at any point:
ByUnicoSDK.close();

El diagrama de secuencia a continuación demuestra cómo usar el SDK y el resultado de la API para configurar el iFrame:

Seguridad

Opta por la solución de iFrame con token de autenticación en lugar de CSP

Tras un análisis cuidadoso, el enfoque elegido utiliza iframes con tokens de autenticación en lugar de implementar una Política de Seguridad de Contenido (CSP). Esta decisión fue motivada por los requisitos de seguridad y la flexibilidad necesaria para satisfacer las demandas de los clientes.

Contexto y desafíos con CSP

La Política de Seguridad de Contenido es una herramienta poderosa para proteger las aplicaciones web contra ataques XSS e inyección de código. Sin embargo, configurar una política CSP requiere definir una lista estricta de dominios de confianza. Este enfoque es efectivo cuando los dominios son fijos y predecibles — pero para clientes que utilizan dominios dinámicos y variables, esta configuración rígida presenta desafíos significativos.

Vulnerabilidad con dominios dinámicos

Los dominios dinámicos representan un riesgo de seguridad sustancial al usar CSP. Cuando un cliente tiene dominios que cambian con frecuencia o se crean dinámicamente, la política CSP debe actualizarse constantemente para incluir los nuevos dominios. Esto no solo aumenta la carga de mantenimiento, sino que también expone cada dominio listado en la política como una superficie de ataque potencial si no se gestiona adecuadamente.

Solución con iFrame y token de autenticación

Para mitigar estos riesgos y satisfacer la flexibilidad requerida por los clientes, la solución elegida combina iframes con tokens de autenticación, proporcionando una capa adicional de seguridad sin requerir una lista estática de dominios.

Cómo funciona:

• Autenticación segura — cada iFrame se carga con un token de autenticación único por transacción, asegurando que solo los usuarios autorizados puedan acceder al contenido. El token se verifica en tiempo real.
• Aislamiento de contenido — el iFrame se ejecuta en un contexto de navegación separado, reduciendo el riesgo de interferencia entre diferentes orígenes y mitigando posibles ataques.
• Flexibilidad para dominios dinámicos — al no depender de una política CSP estática, la solución se adapta a los dominios dinámicos de los clientes sin requerir actualizaciones constantes de la política.