Saltar al contenido principal
Esta página documenta un SDK heredado. ¿Vas a iniciar una nueva integración? Usa el Yuno SDK. ¿Ya usas un SDK heredado? Sigue la guía de migración.El nuevo Yuno SDK (Web v2.x, iOS v3.x, Android v3.x, React Native v2.x) reemplaza los SDK Full, Lite, Seamless, Render, Headless y Secure Fields con una sola API en todas las plataformas. Los SDK heredados siguen siendo compatibles en paralelo durante la transición y está previsto dejarlos de usar en 2027. Contacta a tu Account Manager para planificar la migración.
Orientación: elige tu flujo de integración. Antes de comenzar, revisa el flujo de integración oficial.
  • Flujo estándar (Full Checkout): Recomendado para la mayoría de los comercios. Yuno se encarga de la interfaz, la seguridad y las actualizaciones automáticas de los métodos de pago.
  • Flujo personalizado (este SDK): Úsalo solo si necesitas control total sobre la experiencia de usuario. Nota: Serás responsable de gestionar manualmente los estados de los pagos, las transiciones de 3DS y la recopilación de datos para el enrutamiento de fraude.

El Headless SDK de Yuno te permite crear pagos. Al usar el Headless SDK, ten en cuenta que debes solicitar y enviar por API todos los campos obligatorios que exige el proveedor de pagos. Estos campos son necesarios para generar el pago en su API. El Headless SDK de Yuno te permite crear pagos en dos escenarios distintos:
  • Crear un token de un solo uso con la información de una tarjeta de crédito y luego crear un pago.
  • Crear un token de un solo uso con un vaulted_token de una tarjeta de crédito inscrita previamente y luego crear un pago.
Los siguientes pasos describen cómo crear un pago con el Headless SDK de Yuno.

Paso 1: incluye la biblioteca en tu proyecto

Antes de continuar con la implementación del Headless SDK, consulta la Descripción general de la integración del SDK para ver instrucciones detalladas sobre cómo integrar correctamente el SDK en tu proyecto. La guía de integración ofrece tres métodos flexibles:
  1. Inclusión directa del script HTML
  2. Inyección dinámica de JavaScript
  3. Instalación del módulo NPM
Elige el método de integración que mejor se ajuste a tu flujo de desarrollo y a tus requisitos técnicos. Después de completar la integración del SDK, puedes continuar con los siguientes pasos para implementar la capacidad de checkout Headless.
Biblioteca de TypeScriptSi usas TypeScript, Yuno ofrece una biblioteca que puedes usar para ver todos los métodos disponibles en el Yuno Web SDK.

Paso 2: inicializa el Headless SDK con la clave pública

En tu aplicación JavaScript, crea una instancia de la clase Yuno proporcionando una PUBLIC_API_KEY válida.
CredencialesConsulta la página de credenciales para obtener más información: /reference/getting-started/authentication

Paso 3: inicia el proceso de checkout

A continuación, iniciarás el proceso de checkout con la función apiClientPayment, proporcionando los parámetros de configuración necesarios.

Parámetros

Configura el pago con las siguientes opciones:

Precarga de huellas digitales de fraude

Si tu cuenta usa la detección de fraude con un proveedor cuyo script de huella digital puede tardar más que el tiempo de espera de fraude configurado, llama a executeFraudCheck cuando se renderice el formulario de pago, no en el momento en que tu cliente hace clic en “Pagar”. En algunas regiones, los scripts de huella digital de ciertos proveedores tardan más que el tiempo de espera en cargarse. Llamar a apiClientPayment y generateToken una tras otra al hacer clic puede generar el token de un solo uso antes de que termine de cargarse la huella digital. Esto significa que el token se crearía sin huella digital del dispositivo.

Paso 4: genera el token

Después de recopilar toda la información del usuario, puedes iniciar el pago. Primero, debes crear un token de un solo uso (OTT) con la función apiClientpayment.generateToken. Como es una función asíncrona, puedes usar try/catch para asegurarte de manejar correctamente los errores que se produzcan. Los siguientes ejemplos muestran distintos escenarios para crear el token de un solo uso:
  1. Ejemplo 1: crea un token de un solo uso utilizando una tarjeta como método de pago e incluyendo toda la información necesaria de la tarjeta.
  2. Ejemplo 2: crea un token de un solo uso utilizando la información del vaulted_token.
Para dividir un pago entre dos tarjetas, pasa un arreglo en payment_method. Consulta Divide un pago entre dos tarjetas.
Beneficios de usar un token almacenadoCuando usas un token almacenado con el SDK, se recopila toda la información de fraude de los proveedores que configuraste en tu enrutamiento de tarjetas. Esta información se adjunta al token de un solo uso. Además, puedes agregar información de cuotas y un código de seguridad si el proveedor lo requiere.
Example 1

Parámetros del Ejemplo 1

Example 2

Parámetros del Ejemplo 2

El siguiente bloque de código muestra las respuestas de la función apiClientPayment.generateToken para los dos ejemplos anteriores:
Example 1
Example 2

Paso 5: crea el pago

Después de recibir el token de un solo uso, puedes crear el pago con el endpoint Crear pago para obtener el resultado final del pago. Enviarás el token de un solo uso recibido en el Paso 4 mediante el parámetro payment_method.token de la solicitud. El siguiente bloque de código muestra un ejemplo de solicitud para crear un pago:
La respuesta del endpoint incluye el parámetro sdk_action_required, que define si se necesitan acciones adicionales para concluir el pago:
  • Si tu cliente selecciona un método de pago síncrono, el pago se completa al instante. En este escenario, el campo sdk_action_required de la respuesta de la API será false y el proceso de pago concluye en este paso.
  • Cuando se necesita una interacción adicional del SDK para completar el flujo de pago, sdk_action_required será true. En ese caso, debes seguir las instrucciones del Paso 6.

Paso 6: obtén la URL del desafío 3DS

Como se describe en la página Verificación de tarjetas con 3DS, un pago con 3DS puede requerir un desafío adicional para comprobar la identidad del cliente. Si es necesario un paso de verificación adicional relacionado con un desafío de verificación 3DS, la respuesta del endpoint Crear pago tendrá la siguiente información:
  • Un tipo de transacción THREE_D_SECURE .
  • Estado igual a PENDING y subestado igual a WAITING_ADDITIONAL_STEP.
  • El campo sdk_action_required establecido en true.
Para obtener la URL del desafío 3DS, debes llamar a la función getThreeDSecureChallenge, proporcionando el checkoutSession usado para crear el pago.
Si la tarjeta no requiere un desafío para verificar la identidad del cliente, la url devolverá null. Para un pago dividido entre dos tarjetas, llama a esta función una vez por tarjeta. Consulta Ejecuta el desafío 3DS de cada tarjeta. En un navegador web, puedes abrir la URL en una pestaña nueva o en un IFrame. Para abrir la URL en un iframe, debes establecer el parámetro embedded = true. De lo contrario, puedes omitir este parámetro, cuyo valor predeterminado es false. El siguiente bloque de código muestra un ejemplo de cómo mostrar el contenido del desafío 3DS en un IFrame:
Eres responsable de redirigir a tus clientes a la URL proporcionada en redirect_url para completar el desafío. Cuando el cliente complete con éxito el desafío 3DS, será redirigido automáticamente a la callback_url. Proporcionaste esta callback_url al crear la checkout_session con el endpoint Crear sesión de checkout. Para completar el flujo de pago del Headless SDK, debes usar los webhooks de Yuno. Los webhooks te notifican de inmediato el resultado del desafío 3DS y el estado final del pago, para que recibas actualizaciones en tiempo real sobre el avance de la transacción de pago. Además de los webhooks, puedes consultar la información del pago con el endpoint Consultar pago por ID.

Paso 7: obtén las acciones del pago

A veces el pago puede requerir una acción adicional para continuar el flujo de pago. Para determinar qué acción se necesita, debes llamar al método getContinuePaymentAction, proporcionando el checkoutSession usado para crear el pago.
El método getContinuePaymentAction devuelve un objeto ContinuePaymentAction. Este objeto describe la acción específica necesaria para continuar el flujo de pago, según el proveedor y el paso requerido.

Estructura de la respuesta ContinuePaymentAction

La respuesta contiene información sobre el tipo de acción requerida y los datos necesarios para realizarla:

Campos de ContinuePaymentAction

Tipos de proveedor y acciones

Los siguientes enums definen los proveedores de pagos compatibles y las posibles acciones:

Referencia de tipos de proveedor y acciones

Manejo de los distintos tipos de acción

Según el campo action de la respuesta, debes manejar cada tipo de acción de forma adecuada:

Acción REDIRECT_URL

Cuando la acción es REDIRECT_URL, debes redirigir al usuario a la URL proporcionada en data.redirect.init_url:

Otros tipos de acción

Cada tipo de acción requiere un manejo específico según los datos proporcionados:
  • PAYMENT_CODE: muestra al usuario el código de pago y la referencia
  • IMAGE: muestra al usuario un código QR u otra imagen
  • OTP: presenta al usuario un formulario para ingresar el OTP
  • SDK_PROVIDER: inicializa el SDK del proveedor específico
  • RENDER_IFRAME: muestra un iframe con la interfaz del proveedor
Manejo de acciones de pagoLa implementación específica para manejar cada tipo de acción dependerá del framework de interfaz de usuario de tu aplicación y de sus requisitos. Asegúrate de manejar todos los tipos de acción posibles que podrían devolver los proveedores de pagos que configuraste.
App de demostraciónAdemás de los ejemplos de código proporcionados, puedes acceder a la App de demostración para ver una implementación completa de los SDK de Yuno (clona el repositorio).

Divide un pago entre dos tarjetas

Desde el Web SDK 1.11.43, generateToken puede crear un solo token para un pago que financian dos tarjetas en conjunto. Cada tarjeta paga su propia parte del monto. El flujo es solo headless: no hay una interfaz de checkout para esto. Para conocer la habilitación, los estados, las reversiones, las operaciones y los errores, consulta Paga con dos tarjetas.
VersiónNecesitas el Web SDK 1.11.43 o posterior. Si cargas el SDK desde https://sdk-web.y.uno/v1.11/main.js, ya lo tienes. Si lo instalas desde npm, ejecuta npm install @yuno-payments/sdk-web@^9: el paquete 9.x carga la línea v1.11 desde la CDN, que sirve la 1.11.43 o posterior. La versión 10.x del paquete carga el Web SDK v2.

Genera un token para ambas tarjetas

Pasa payment_method como un arreglo con exactamente dos elementos, uno por tarjeta, en lugar de un solo objeto. Cada elemento recibe los mismos campos que un método de pago individual (type, card o vaulted_token, customer, device_fingerprints, third_party_data) más el amount que paga esa tarjeta. Envía total junto a payment_method: sin él, el pago se rechaza más adelante.
El SDK recopila los datos de fraude y la información del navegador de cada elemento, igual que con una sola tarjeta. Cuando pasas un arreglo, la función se resuelve con un único token compuesto:
Cuando pasas un objeto, generateToken se comporta como antes y devuelve la respuesta que se muestra en el Paso 4. Las integraciones existentes no cambian. El SDK valida el arreglo antes de enviar cualquier solicitud y lanza un error que indica el elemento con el problema. Envuelve la llamada en try/catch.

Crea el pago

Crea el pago desde tu servidor con POST /v2/payments (https://api.y.uno/v2/payments en producción, o https://api-sandbox.y.uno/v2/payments en sandbox). Usa los mismos encabezados de autenticación que los demás endpoints de pagos. El endpoint Crear pago v1 del Paso 5 es para un token de un solo método de pago; un token compuesto va a POST /v2/payments.
Para leer el resultado de cada tarjeta, llama a GET /v2/payments/{payment_id} desde tu servidor con los mismos encabezados de autenticación. Su arreglo payment_method.payment_methods tiene una entrada por tarjeta, cada una con su sequence (la posición de la tarjeta en el token), type, amount y transactions. Una tarjeta no tiene un estado propio: lee el resultado de cada tarjeta a partir de sus transacciones, donde la transacción THREE_D_SECURE de la tarjeta lleva el resultado de su desafío. El status y el sub_status a nivel de pago resumen ambas tarjetas. El endpoint Consultar pago v1 muestra el pago en conjunto, no cada tarjeta. Consulta Paga con dos tarjetas para ver la respuesta completa, los estados y las operaciones, y la referencia Consultar pago (dos tarjetas).

Ejecuta el desafío 3DS de cada tarjeta

Cuando las tarjetas necesitan 3DS, llama a getThreeDSecureChallenge una vez por tarjeta, en el orden del arreglo payment_method. Renderiza cada URL que devuelva como se describe en el Paso 6 y espera a que ese desafío termine antes de volver a llamarla. Cada llamada devuelve el desafío de la primera tarjeta, en el orden del arreglo, que sigue esperando 3DS. Una tarjeta que no necesita desafío se omite, de modo que la siguiente llamada ya devuelve la siguiente tarjeta que lo necesita. Cuando ya no queda ninguna tarjeta esperando 3DS, la llamada se resuelve con url: null: esa es la señal para detenerte, nunca una indicación de que una tarjeta estuvo exenta. Yuno registra el resultado de un desafío unos segundos después de que el cliente lo completa, así que espera hasta que la transacción THREE_D_SECURE de la tarjeta deje de estar en PENDING (mediante tu webhook o GET /v2/payments/{payment_id}) antes de llamar a getThreeDSecureChallenge para la siguiente tarjeta; una llamada hecha antes puede devolver de nuevo el desafío de la misma tarjeta.
Un pago realizado con una sola tarjeta se comporta como antes: una llamada, un desafío.

Cómo procesa Yuno las dos tarjetas

  • Una tarjeta que necesita 3DS se cobra apenas termina su propio desafío. Una tarjeta que no necesita 3DS se cobra cuando se crea el pago.
  • Si el desafío de una tarjeta falla o su emisor la rechaza, todo el pago termina. Yuno revierte el cobro de una tarjeta que ya se haya cobrado y cancela el 3DS pendiente de la otra tarjeta. No le pidas a tu cliente que continúe con la tarjeta restante: inicia un pago nuevo.
  • El pago final tiene una entrada por tarjeta en payment_method.payment_methods, cada una con su sequence, type, amount y transactions. No hay un estado por tarjeta: lee el resultado de cada tarjeta a partir de sus transacciones. Léelo desde tus webhooks o con GET /v2/payments/{payment_id}.

Manejo de errores

Maneja en tu aplicación los errores que devuelve el SDK, como pagos fallidos o errores de validación. Para los códigos de estado HTTP y de respuesta, consulta Códigos de estado y de respuesta en la referencia de la API. Para hacer un reembolso de un pago, consulta Reembolsar pagos y la API Reembolsar pago.

Mantente al día

Visita el changelog para ver las últimas actualizaciones del SDK y el historial de versiones.