Saltar al contenido principal

SDK

Para el uso web, el enfoque recomendado es usar el SDK de Unico por las siguientes razones:

  • Mayor seguridad;
  • Experiencia integrada con tu flujo;
  • Mayor tasa de conversión al usar el SDK;
  • Implementación más sencilla.
advertencia

El uso de integraciones que no cumplan con los estándares establecidos en esta documentación puede generar interrupciones inesperadas en el funcionamiento del sistema, las cuales no serán cubiertas ni soportadas por Verificación de Tarjeta No Presente.

Por ejemplo: Implementar Unico por iFrame dentro de un webview, implementar el iFrame mediante una etiqueta HTML, etc.

Lineamientos generales​

Para optimizar el rendimiento de tu operación, mejorar las tasas de conversión y ofrecer una experiencia de usuario más fluida, es obligatorio implementar el SDK de Unico en modo de pantalla completa en tu aplicación.

Cómo empezar​

Para usar Verificación de Tarjeta No Presente a través del SDK de Verificación de Tarjeta No Presente, el primer paso es registrar los dominios que se utilizarán como hosts para mostrar la experiencia del recorrido del usuario.

peligro

Notifica a la persona responsable de tu proyecto de integración o al equipo de soporte de Unico para realizar esta configuración.

Para comenzar a usar el SDK, debemos empezar con la instalación del SDK web de Unico:

npm install idpay-b2b-sdk
consejo

Al instalar el paquete del SDK de Unico, despliega sin especificar la versión que estás usando, para que tu gestor de dependencias siempre actualice las versiones menores y los parches a la última versión.

Para consultar versiones anteriores, ve a npmjs.com/package/idpay-b2b-sdk.

Métodos disponibles​

init(options)​

Este método permite inicializar el SDK, independientemente de un ID de transacción, haciendo que la experiencia del usuario final sea más fluida. Esto se debe a que, cuando el ID de transacción y el token estén disponibles, la aplicación ya habrá sido precargada mediante este método. Si este método no es llamado directamente por la aplicación, el usuario final experimentará un tiempo de carga prolongado cuando el SDK se abra por primera vez.

Parámetros:

  • options — recibe un objeto con propiedades de configuración:
    • type — el tipo de flujo que se inicializará. Actualmente, ofrecemos el tipo IFRAME. Para nuevas aplicaciones, recomendamos usar el tipo IFRAME, que hace que la experiencia del usuario final sea mucho más fluida y con menos fricción, ya que evita la necesidad de salir de la pantalla de checkout, y la experiencia puede precargarse.
import { IDPaySDK } from "idpay-b2b-sdk";

IDPaySDK.init({
  type: 'IFRAME',
  env: 'uat' // Only needed for the test environment.
});

open({ transactionId, token, onFinish? })​

Este método abre la experiencia de Verificación de Tarjeta No Presente según el tipo de flujo elegido previamente en la función de inicialización. Para el flujo REDIRECT, esta función realiza una redirección simple a la ruta del flujo de captura de Verificación de Tarjeta No Presente. Para el flujo IFRAME, esta función muestra el iframe precargado e inicia el flujo de mensajería entre la página del cliente y la experiencia de Verificación de Tarjeta No Presente.

Parámetros:

  • options — recibe un objeto con propiedades de configuración:
    • transactionId — recibe el ID de la transacción creada. Este ID es importante para obtener los detalles de la transacción y completar el flujo correctamente (se puede obtener durante la creación de la transacción a través de la API).
    • token — recibe el token de la transacción creada. Este token es importante para autenticar la transacción y garantizar que solo los dominios autorizados lo usen (se puede obtener durante la creación de la transacción a través de la API).
    • onFinish(transaction, type) (opcional) — recibe una función de callback que se ejecutará al final del flujo de captura de Verificación de Tarjeta No Presente, pasando dos argumentos: el objeto de la transacción ({ captureConcluded, concluded, id }), y el tipo de respuesta — FINISH para los casos en que el flujo se completó con éxito, o ERROR para los casos en que el flujo se interrumpió por un error. En los casos de error en el flujo, el estado de la transacción no cambiará, y no se activará un callback vía webhook, si estuviera configurado.
const transactionId = '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf';
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

const transaction = {
  id: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  concluded: true,
  captureConcluded: true
};

const onFinish = (transaction, type) => {
  console.log('response', transaction, type);
}

IDPaySDK.open({
  transactionId,
  token,
  onFinish
});

// You can also close the SDK explicitly using the method below
IDPaySDK.close();

Seguridad​

Después de un análisis cuidadoso de las necesidades y desafíos que enfrentamos, decidimos adoptar una solución basada en iFrames con tokens de autenticación en lugar de implementar una Content Security Policy (CSP). Esta decisión se basó en varias consideraciones relacionadas con la seguridad y la flexibilidad requerida para satisfacer las demandas de nuestros clientes.

Contexto y desafíos con CSP​

La Content Security Policy (CSP) es una herramienta poderosa para proteger aplicaciones web contra varios tipos de ataques, como Cross-Site Scripting (XSS) e inyección de código. Sin embargo, al configurar una política de CSP, es necesario definir una lista estricta de dominios confiables. Este enfoque funciona bien cuando los dominios son fijos y predecibles. Sin embargo, para nuestros clientes que suelen usar 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, sería necesario actualizar constantemente la política de CSP para incluir estos nuevos dominios. Esto no solo aumenta el esfuerzo de mantenimiento, sino que también expone los dominios a los que se aplica la política de CSP. Cada dominio agregado a la política de CSP es potencialmente un punto de vulnerabilidad si no se gestiona adecuadamente.

Solución con iFrame y token de autenticación​

Para mitigar estos riesgos y satisfacer la flexibilidad requerida por nuestros clientes, optamos por usar iFrames combinados con tokens de autenticación. Esta solución proporciona una capa adicional de seguridad y elimina la necesidad de exponer o gestionar una lista extensa y dinámica de dominios.

Cómo funciona​

  • Autenticación segura: Cada iframe se carga con un token de autenticación único para cada transacción, garantizando que solo usuarios autorizados puedan acceder al contenido. Este token se verifica en tiempo real, proporcionando una capa adicional de seguridad y control.
  • Aislamiento de contenido: El uso de iFrames permite que el contenido se aísle en un contexto 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 de CSP estática, nuestra solución se adapta fácilmente a los dominios dinámicos de los clientes sin necesidad de actualizaciones constantes de las políticas de seguridad.
Última actualización el