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.
Compatibilidad con TypeScript
TypeScript: Yuno ofrece una biblioteca de TypeScript para todos los métodos disponibles.Subresource Integrity (SRI)
Esta función de seguridad del navegador te permite asegurar que un script cargado no ha sido manipulado. Proporcionas un hash criptográfico junto con la URL del script. El navegador verifica que los bytes descargados coincidan con el hash declarado antes de ejecutar el código.- Integridad: garantiza que el código exacto que se compiló y publicó es el que se ejecuta en el navegador.
- Inmutabilidad: combinada con URL de versión semántica completa, asegura integraciones estables y reproducibles.
- Defensa en profundidad: reduce los riesgos de un compromiso de la cadena de suministro o de la capa de transporte.
Formatos de URL
Al implementar SRI, usa el formato de URL de versión semántica completa para asegurar integraciones inmutables y a prueba de manipulaciones.- URL completa (inmutable) con SRI: ruta de versión semántica completa que se usa para integraciones bloqueadas y a prueba de manipulaciones con un hash de SRI.
- URL parcial (mutable): versión con mayor y menor (por ejemplo, v1.9). Esta versión recibirá mejoras de parche. Es útil si prefieres evitar actualizaciones en tu base de código.
Cómo integrar el SDK con SRI
Reemplazasrc e integrity con el entorno y la versión que usas. crossorigin="anonymous" permite que el navegador valide el SRI de los scripts de origen cruzado.
Puedes encontrar el hash en versions-sri.json, en latest.integrity o dentro del arreglo history.
url publicada junto con el hash en versions-sri.json: cada entrada asocia una url de versión completa con el integrity que le corresponde, por ejemplo https://prod.y.uno/sdk-static-bundles-ms/sdk-web/v1.10.6/main.js.
SRI solo funciona con estas URL de versión completa. Las rutas globales, como
https://sdk-web.y.uno/v1.10/main.js, se vuelven a publicar con cada versión de parche, por lo que ningún hash sigue siendo válido para ellas y no se publica ninguno.Uso del paquete de NPM
Notas de validación
- Abre la pestaña Network de DevTools y confirma que main.js devuelve
200desde la ruta de versión completa. - Verifica que los encabezados de la respuesta permitan solicitudes de origen cruzado para recursos estáticos si se sirven desde un origen distinto (
crossorigin="anonymous"está definido). - Asegúrate de que el atributo integrity coincida exactamente con el hash generado, incluido el prefijo sha384-.
- Cualquier cambio en main.js cambia el hash. Al cambiar de versión, siempre vuelve a generar u obtén el nuevo valor sha384 y actualiza el atributo integrity.
Solución de problemas de SRI
- Las discrepancias de hash hacen que el script falle al ejecutarse con un error de integridad (por ejemplo, actualizaste el archivo pero no el hash). Para solucionarlo, vuelve a compilar, obtén el nuevo sha384 de versions-sri.json y actualiza integrity.
-
El navegador bloquea SRI en una solicitud de origen cruzado cuando falta el atributo crossorigin o CORS es restrictivo. Para solucionarlo, agrega
crossorigin="anonymous"y configura el alojamiento estático para permitir solicitudes de origen cruzado de los recursos JS.
Precarga del script del SDK
Cuando usas el paquete de NPM, el navegador solo empieza a descargarmain.js cuando tu app llama a loadScript(). En una aplicación de una sola página, esa llamada suele ejecutarse varios segundos después de la navegación, una vez que tu propio bundle se descargó y se ejecutó. En una conexión móvil lenta, ese retraso, más la propia descarga, puede añadir varios segundos antes de que el SDK se ejecute.
Informa al navegador sobre el script y los hosts de Yuno desde el <head> de tu HTML, para que la descarga y las conexiones comiencen mientras la página aún se está analizando.
Configuración recomendada
Agrega estas etiquetas como los primeros elementos de<head>, antes del bundle de tu app. Este ejemplo es para una cuenta de producción en la región de EE. UU., con @yuno-payments/sdk-web 9.x:
loadScript() tal como está:
loadScript() sigue inyectando la etiqueta <script>. Como el archivo ya está en la caché de precarga del navegador, este usa esa copia en lugar de descargarla otra vez.
Haz coincidir la URL de precarga con tus opciones de loadScript
La precarga solo ayuda cuando su href es exactamente la URL que solicita loadScript(). Esa URL depende de las opciones que pases. Para @yuno-payments/sdk-web 9.x (SDK v1.11):
El host de la API sigue el entorno y la región de tu clave de API pública, por lo que es el mismo host al que llama tu backend. El host del formulario de tarjeta sigue el host desde el que se cargó
main.js.
Con sri: true, la etiqueta de precarga se ve así:
Con
sri: true, el paquete fija una versión específica del SDK y su hash. Usa esa versión en la precarga, no la entrada latest de versions-sri.json, que normalmente es más reciente que la versión que carga tu paquete.<script id="sdk-payments-script"> que agrega loadScript(). Copia su src y, cuando esté presente, su integrity.
Reglas:
- Mantén
crossoriginen la preconexión de la API. El SDK abre la misma preconexión cuando se inicializa. Sin el atributo, el navegador abre una conexión que sus solicitudes CORS a la API no pueden reutilizar. - Con
sri: true, agregacrossorigin="anonymous"a la precarga. El script inyectado usa ese modo. Si la precarga y el script usan modos distintos, el navegador descarga el archivo dos veces. - Una discrepancia no rompe nada. Si la URL o el modo no coinciden, el navegador descarga
main.jsdos veces y DevTools registra una advertencia de que el recurso precargado no se usó. Pierdes la mejora de velocidad, nada más.
Mantén actualizada la URL de precarga
La URL de precarga está escrita en tu HTML, por lo que no cambia cuando actualizas el paquete. Actualízala tú mismo:- Sin SRI, la URL contiene solo la versión mayor y menor del SDK (
v1.11). Las versiones de parche no requieren cambios. Actualízala cuando una versión del paquete pase a una nueva versión menor del SDK (por ejemplo, 7.x cargav1.9, 8.x cargav1.10, 9.x cargav1.11); el README de la versión que instalas indica cuál carga. - Con SRI, la URL y el hash fijan la versión completa del SDK (por ejemplo,
v1.11.1). Actualiza ambos en cada actualización del paquete que cambie esa versión.
Cuando actualices
@yuno-payments/sdk-web, actualiza el href de la precarga (y integrity si usas SRI) a la URL que carga la nueva versión. El README del paquete en npm indica la versión del SDK que carga. Para el hash, usa la entrada de esa versión en la lista history de versions-sri.json (sandbox: sdk-web.sandbox.y.uno/versions-sri.json), o copia ambos valores de la etiqueta <script id="sdk-payments-script"> en DevTools.Verifica que funciona
Abre DevTools, ve al panel Network y recarga la página.main.js debería aparecer una sola vez, con Initiator establecido en la etiqueta de precarga de tu HTML y una hora de inicio cercana al comienzo de la carga de la página. Si main.js aparece dos veces, o la Console muestra que el recurso precargado no se usó, el href de la precarga o el modo crossorigin no coincide con lo que solicita loadScript().
Parámetros clave (creación de la sesión de checkout)
Al crear una sesión de checkout en tu backend, los siguientes parámetros se usan comúnmente en todos los SDK web:Parámetros de pago y checkout (referencia completa)
Parámetros paraawait yuno.startCheckout(), await yuno.mountCheckout() y los flujos de pago relacionados. Todos los parámetros que se usan en Flujos de pago (Web) se enumeran aquí con todo detalle.
Parámetros principales
Callbacks
Nombres de los callbacks. Estos callbacks se renombraron con nombres neutros para marca blanca en Web SDK v1.9.0 (consulta las notas de la versión). Los nombres anteriores con prefijo
yuno (yunoCreatePayment, yunoPaymentMethodSelected, yunoPaymentResult, yunoError y yunoEnrollmentStatus) siguen funcionando como alias, por lo que las integraciones existentes no necesitan cambios. Están obsoletos y se eliminarán en una futura versión mayor. En versiones del SDK anteriores a v1.9.0, usa los nombres con prefijo yuno.Promociones
Cuando Promociones está habilitado para tu organización, el SDK le pide a Yuno una cotización de promoción mientras el comprador completa el pago, le muestra al comprador que hay un descuento disponible y entrega la promoción a tu página. El SDK no cambia el precio: tu página lo muestra y tu servidor envía la cotización con el pago. Consulta la guía de Promociones para ver el flujo completo.- Dónde aplica. Checkout completo (
mountCheckout) y checkout Lite (mountCheckoutLite), solo tarjetas: una tarjeta que el comprador escribe y las tarjetas guardadas del comprador. Seamless no solicita cotizaciones y no aplica promociones. Las billeteras y los botones externos (mountExternalButtons) no reciben cotización en esta versión. - Cuándo la solicita. Tan pronto como el SDK identifica la tarjeta a partir de los primeros dígitos que escribe el comprador, y de nuevo cuando se conoce el tipo de tarjeta. Cada tarjeta guardada se consulta una vez, con su propio token, hasta un máximo de 5 tarjetas guardadas. La solicitud lleva tu clave pública, la sesión de checkout y el
countryCodeque enviaste, y no incluye ningún monto, por lo quecountryCodedebe coincidir con el país de la sesión. - Qué ve el comprador. Una etiqueta, nunca un precio: una nota en el formulario de tarjeta (“Tu tarjeta tiene un 10% de descuento disponible.”) o una etiqueta en el método de pago o la tarjeta guardada a la que aplica (“10% de descuento”). Yuno decide dónde va la etiqueta; no hay nada que configurar.
- Cuando no aplica nada. El SDK no muestra ninguna etiqueta y tu página mantiene el precio regular: no hay promoción (
204, que también cubre el caso en que Yuno desactiva temporalmente Promociones y el de una promoción que dejaría el cargo en cero), un error, una respuesta que tarda más de 600 ms, o una cotización que ya venció cuando llega. Una cotización nunca bloquea el checkout. - Conversión de moneda. Un pago con una promoción de Yuno no puede incluir una conversión de moneda: Yuno lo rechaza con
422 PROMOTION_CONTEXT_MISMATCH, porque una promoción tiene precio en la moneda del propio pago. No uses ambas en el mismo pago.
onPromotionQuoteUpdated(offer) recibe la promoción que aplica al método de pago que el comprador ha seleccionado (para una tarjeta guardada, a esa tarjeta). Recibe null siempre que no haya ninguna para lo que el comprador tiene ahora: no aplica ninguna promoción, el comprador cambia el número de tarjeta o el método de pago, la cotización vence o el checkout se desmonta. Cuando el SDK consulta de nuevo (más dígitos de la tarjeta, el tipo de tarjeta, una cotización a punto de vencer), sigue una nueva promoción si alguna aplica, por lo que null puede llegar justo antes: actualiza tu precio con la última llamada y no animes un cambio en cada callback.
Envía la cotización con el pago. Cuando hay una cotización vigente para el método de pago del token (para una tarjeta, una cotización cuyo BIN coincide con la tarjeta; para una tarjeta guardada, esa tarjeta),
tokenWithInformation.quote contiene la línea de descuento, lista para enviar: { "type": "YUNO_PROMOTION", "quote_id": "…" }. De lo contrario, está ausente y creas el pago al precio regular. Crea el pago desde tu servidor con el amount original y additional_data.order.discounts: [tokenWithInformation.quote]. La cotización no viaja con el token: sin la línea, el pago se cobra completo.
Cuando Yuno rechaza la cotización. Un pago que lleva una cotización vencida se rechaza con 422 PROMOTION_QUOTE_EXPIRED, y uno que Yuno no puede verificar a tiempo, o que se envía después de que Yuno desactivó temporalmente Promociones, con 422 PROMOTION_ENGINE_UNAVAILABLE. Cuando tu servidor recibe el rechazo, el SDK ya cerró el checkout (lo hace justo después de entregarte el token), por lo que no puede pedir una nueva cotización por sí solo. Puedes montar el checkout de nuevo (el SDK cotiza otra vez cuando el comprador vuelve a ingresar la tarjeta, y llega una nueva promoción a través de onPromotionQuoteUpdated si aún aplica) o crear el pago de nuevo sin la línea de promoción y con un nuevo X-Idempotency-Key, al precio regular.
Pasos cancelados por el comprador
Algunos pasos se muestran en un modal que el comprador puede cerrar: el desafío 3DS (cerrándolo con la X o presionando el botón de retroceso del navegador) y las pantallas de instrucciones de pago, como vouchers o códigos de pago. Cuando eso ocurre, el SDK informa:error para estos pasos. Cerrar el modal cierra la interfaz del SDK, pero no cancela el pago. El pago sigue en curso y lo resuelven el proveedor y el backend de Yuno. El backend de Yuno sigue siendo la fuente de verdad del estado final. En particular, un desafío 3DS se ejecuta dentro del propio iframe del emisor, por lo que el SDK no puede determinar si la autenticación ya se completó en el momento en que el comprador cierra el modal. Informar allí una cancelación terminal podría contradecir un pago que luego resulte aprobado.
CANCELLED_BY_USER lo produce el SDK para describir el gesto del comprador. No es un subestado de pago y no aparece en la referencia de estados de pago.subStatus para detectar este caso:
Opciones del formulario de tarjeta (card)
Modo de renderizado
Textos personalizados
Estilo de los botones exprés (externalButtons)
La propiedad externalButtons en startCheckout y startSeamlessCheckout (SDK 1.6+) permite a los comercios personalizar la apariencia de los botones exprés de Google Pay, Apple Pay y PayPal. Todas las propiedades son opcionales; se usan valores predeterminados razonables cuando no se proporcionan. También la acepta mountEnrollmentLite (SDK 1.10.13+) para el botón de inscripción de PayPal; consulta Inscripción de PayPal con el modo de renderizado element, que tiene sus propios valores predeterminados.
La configuración de
externalButtons aplica a todos los flujos que renderizan botones exprés (incluidos mountCheckout, mountExternalButtons y mountSeamlessExternalButtons), siempre que se haya llamado primero a startCheckout o startSeamlessCheckout con la configuración. Para el flujo de inscripción, pásala directamente a mountEnrollmentLite.Google Pay
Apple Pay
PayPal
PayPal Braintree
Para los comercios que usan PayPal procesado a través de Braintree, personaliza el estilo de los botones y los callbacks de envío medianteexternalButtons.paypalBraintree:
onShippingAddressChange recibe { shippingAddress: { city, state, postalCode, countryCode }, paypalOrderId } y devuelve una Promise con uno de estos valores:
{ action: 'ACCEPT' }{ action: 'UPDATE_PRICE', amount, breakdown?: { itemTotal, shipping?, tax? } }{ action: 'REJECT', reason?: 'COUNTRY' | 'STATE' | 'POSTAL_CODE' | 'ADDRESS' }
paypalBraintree también acepta shippingAddressOverride, una función que devuelve la dirección que se precargará, o undefined.
Ejemplo completo
Reintento de pago
El reintento de pago permite que un comprador corrija y vuelva a enviar un pago con tarjeta después de que regresa comoDECLINED o ERROR, sin reiniciar el checkout. En lugar de desmontar el formulario de tarjeta, el SDK lo mantiene abierto y muestra el rechazo (errores a nivel de campo y un banner de error en la parte superior). También clona la sesión de checkout para que el siguiente intento reutilice el mismo flujo.
El reintento está desactivado de forma predeterminada. Yuno lo habilita por organización, a solicitud, mediante una marca del lado del servidor; no es un interruptor del Dashboard ni del Checkout Builder. Es una configuración controlada por el servidor, no un argumento de startCheckout(). Aplica solo a pagos con tarjetas no inscritas. Las tarjetas inscritas, las tarjetas guardadas (vaulted) y los pagos con botones externos quedan excluidos.
El reintento de pago es compatible con las cuatro integraciones Web: Seamless, Full Checkout, Lite y Secure Fields.
El reintento en Lite se lanzó en el SDK v1.9.11.
Comportamiento por integración
Cómo activar el reintento en Full Checkout, Lite y Secure Fields
En estos tres flujos, después de que tu backend cree el pago, debes inspeccionar la respuesta del pago y dirigir el SDK en consecuencia:- Pago con tarjeta fallido (
payment_method.type === 'CARD'ystatusesDECLINEDoERROR): llama acontinuePaymentpara ejecutar el reintento. El formulario de tarjeta permanece abierto mostrando el rechazo. - Se requiere una acción adicional (
checkout.sdk_action_required === true): llama acontinuePaymentpara que el SDK pueda mostrar las pantallas necesarias (por ejemplo, 3DS o una redirección). - Al SDK no le queda nada por hacer (el estado no es
DECLINED/ERRORycheckout.sdk_action_required === false): el SDK no se desmontará por sí mismo, por lo que debes desmontarlo manualmente conunmountSdk.
Ciclo de vida del reintento y callbacks
En un intento reintentado, el SDK no disparapaymentResult y no monta la página de estado. En su lugar, entrega la sesión de checkout clonada a tu callback onLoading:
createPayment → tu backend → continuePayment (o de forma automática en Seamless) sin un callback paymentResult entre intentos. paymentResult se dispara solo cuando el flujo termina: el pago es exitoso, el comprador sale, o el pago falla sin poder reintentarse.
Consentimiento de débito directo
Disponible desde Web SDK v1.10.12. En los métodos de pago de débito directo (ACH, SEPA Direct Debit, Bacs, PAD e iDEAL cuando se guarda la cuenta), el checkout muestra el texto de autorización o mandato debajo de los campos del banco, cuando se habilita desde el panel Authorization text del Checkout Builder.- El texto de pago único se muestra de forma predeterminada.
- El texto recurrente se muestra en su lugar cuando la cuenta se va a almacenar: o bien el comprador marcó la casilla de guardado
savePaymentMethodEnabled, o bien el flujo es una inscripción.
Evidencia del mandato en el token de un solo uso
Siempre que se muestra el bloque de texto de autorización, el SDK incluye la evidencia de aceptación del comprador en el token de un solo uso, sin importar si se marcó la casilla de guardado. La estructura de abajo refleja lo que se codifica dentro de ese token; tu backend lo sigue reenviando a Create Payment como la cadena opacapayment_method.token, igual que cualquier otro token de un solo uso:
updateCheckoutSession
updateCheckoutSession(checkoutSession) reemplaza la sesión de checkout activa sin desmontar el SDK. Úsalo para permitir que el comprador cambie a otro método de pago después de un pago fallido.
yuno.updateCheckoutSession() se propaga automáticamente a la instancia de Secure Fields; no es necesario llamarlo directamente en la instancia SF.isPaymentMethodAvailable
isPaymentMethodAvailable({ paymentMethodType, checkoutSession? }) se resuelve en true o false: indica si el método de pago se mostrará para el comprador y la sesión de checkout actuales. Úsalo cuando dibujes tu propia lista de métodos de pago (Lite, Seamless Lite o botones exprés ubicados dentro de tu propia lista) para mostrar solo los métodos que el SDK puede renderizar.
- Habilitado para la sesión de checkout. El método debe ser uno de los métodos de pago de la sesión y estar habilitado para ella. De lo contrario, la respuesta es
false. - Comprobación de dispositivo y navegador, para los métodos que la necesitan. El SDK ejecuta la misma comprobación que ejecuta antes de mostrar ese método:
false, igual que el SDK, que no renderiza el método en ese caso. El único respaldo es el propio del SDK: cuando falla la llamada a applePayCapabilities() de Apple, decide ApplePaySession.canMakePayments(). Sin una sesión de checkout (sin startCheckout y sin el argumento checkoutSession) se resuelve en false.
Disponible en Web SDK 1.11.43 y posteriores, y desde 1.10.35. Las líneas 1.9 y anteriores no lo tienen. Los tipos están en
@yuno-payments/sdk-web-types 5.14.0 y @yuno-payments/sdk-web 9.10.0. En el Universal Web SDK, llama a transaction.isPaymentMethodAvailable({ paymentMethodType }): usa la sesión de checkout de la transacción y no está disponible en las transacciones de inscripción.Parámetros de inscripción (referencia completa)
Parámetros paraawait yuno.mountEnrollmentLite(). Todos los parámetros que se usan en Flujos de inscripción (Web) se enumeran aquí con todo detalle.
Montar botones externos
Usa el métodomountExternalButtons para renderizar los botones de PayPal, Google Pay, Apple Pay y Samsung Pay en ubicaciones personalizadas dentro de tu interfaz. Esto te da control sobre dónde se muestran estos botones.
Un botón de billetera se renderiza solo cuando el método de pago está habilitado para la sesión de checkout y supera la misma comprobación de dispositivo y navegador descrita en
isPaymentMethodAvailable, por lo que el mismo código puede mostrar un botón de billetera en un dispositivo o navegador y no en otro. En Web SDK 1.11.43 y posteriores, o 1.10.35 y posteriores, llama a isPaymentMethodAvailable para cada billetera antes de montarla para saber si su botón se renderizará.Parámetros
Desmontar botones
Puedes desmontar un solo botón externo por tipo de método de pago:Inscripción de métodos de pago
Puedes inscribir métodos de pago (almacenar tarjetas para uso futuro) directamente durante el flujo de pago, configurandopayment_method.vault_on_success = true en la creación de la sesión de checkout.
Cuando vault_on_success se establece en true:
- El método de pago se inscribirá automáticamente si el estado del pago es
SUCCEEDED - Si el pago no es exitoso, no se almacenará nada
- La respuesta del pago incluirá un
vaulted_tokenque puedes usar para transacciones futuras
vaulted_token cuando vault_on_success = true, el pago debe hacer referencia a un cliente de Yuno existente mediante customer_payer.id en la sesión de checkout. Crear o enviar los datos del cliente en línea dentro de la solicitud de pago no crea al cliente de nuestro lado. Como resultado, no se almacenará nada.
Para los flujos de inscripción, consulta Flujos de inscripción (Web).