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.
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_tokende una tarjeta de crédito inscrita previamente y luego crear un pago.
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:- Inclusión directa del script HTML
- Inyección dinámica de JavaScript
- Instalación del módulo NPM
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 claseYuno 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ónapiClientPayment, 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 aexecuteFraudCheck 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ónapiClientpayment.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:
- 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.
- Ejemplo 2: crea un token de un solo uso utilizando la información del
vaulted_token.
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ámetropayment_method.token de la solicitud. El siguiente bloque de código muestra un ejemplo de solicitud para crear un pago:
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_requiredde la respuesta de la API seráfalsey 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_requiredserá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
PENDINGy subestado igual aWAITING_ADDITIONAL_STEP. - El campo
sdk_action_requiredestablecido entrue.
getThreeDSecureChallenge, proporcionando el checkoutSession usado para crear el pago.
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:
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étodogetContinuePaymentAction, proporcionando el checkoutSession usado para crear el pago.
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 campoaction 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
Pasapayment_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:
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 conPOST /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 agetThreeDSecureChallenge 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.
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 susequence,type,amountytransactions. No hay un estado por tarjeta: lee el resultado de cada tarjeta a partir de sus transacciones. Léelo desde tus webhooks o conGET /v2/payments/{payment_id}.