Saltar al contenido principal
Copia este archivo en la raíz de tu proyecto y pídele a tu agente de código:
Indica qué debo cambiar para pasar mi integración del Web SDK de Yuno a v2, siguiendo este archivo.
Funciona como CLAUDE.md, AGENTS.md o como prompt pegado, con Claude Code, Cursor, Codex o Copilot. Es de solo lectura: analiza tu código y reporta, y no cambia nada a menos que lo pidas. El destino. v2 es la línea 2.x de sdk-web (“Yuno SDK 2.x”, la Transaction API unificada). Consulta el changelog del Web SDK para ver la versión actual. Cada versión se sirve en una URL con la versión completa, por ejemplo https://sdk-web.y.uno/v2.5.1/main.js, y v2.0.0, v2.1.0, v2.1.2, v2.2.0 también están disponibles. No hay una carpeta rolling: /v2/, /v2.0/ y /v2.2/ devuelven 404, por lo que debes fijar una versión completa y actualizarla a mano. La ruta SRI es https://prod.y.uno/sdk-static-bundles-ms/sdk-web/v2.5.1/main.js. Documentación pública: la pestaña “SDK” (docs/yuno-sdk/*, serie de migración en docs/yuno-sdk/migration/web/*). La pestaña “SDKs” es la línea 1.x. v1.x sigue con soporte en paralelo hasta 2027. El origen. v1.11 (window.Yuno, /v1.11/main.js rolling), la línea 1.x actual.

Lo que v2 mantiene (no lo reportes como bloqueante)

  • v2 no mantiene ningún alias de v1. Solo define window.SdkPayments y solo despacha sdk-payments-ready. No define window.Yuno y nunca dispara yuno-sdk-ready. Todo uso de window.Yuno y yuno-sdk-ready debe cambiar.
  • v1.11 ya expone los nombres de v2. Define ambos globales y dispara ambos eventos. Por lo tanto, window.SdkPayments y sdk-payments-ready en un repositorio con v1.11 ya son correctos. Ese cambio de nombre se puede publicar en 1.11 primero, antes de cambiar el script.
  • Sin cambios en v2: el prefijo CSS sdk-payments-*; las claves de opciones de initialize (cookies, sdkType, apiUrl, assetUrl, plugin); clearApiCache() y setCanaryMode() en la instancia; onChange(state); las opciones onPromotionQuoteUpdated, externalButtons, texts, issuersFormEnable, showPayButton, deviceFingerprints, paymentListConfig, savePaymentMethodEnabled; las claves de card styles, type (excepto 'step'), vaultOnSuccess, texts, documentEnable, isCreditCardProcessingOnly, fonts, onChange, onGetInstallments, onInstallmentSelected.
  • Claves silenciosas. v2 reenvía claves de configuración desconocidas o exclusivas de v1 sin ningún error. La mayoría nunca se leen: la funcionalidad que controlaban simplemente desaparece. Marca esas filas como SILENT. Tres claves de v1 todavía se leen en 2.2.0: onLoading todavía se llama cuando no hay una función showLoading; paymentMethodSelected y yunoPaymentMethodSelected todavía se disparan en cada selección de la lista, por lo que mantener una junto a onPaymentSelected produce dos llamadas por selección; yunoCreatePayment se fusiona en createPayment en el estado. Renómbralas de todos modos.
  • CSS. v2 renderiza yuno-container-spinner-content y yuno-container-spinner-ring (el spinner de carga de cada montaje) y define data-yuno-placeholder. Son nombres de v2: nunca reportes selectores sobre ellos.

Cómo usarlo

  1. Encuentra la superficie de v1. Ejecuta esto sobre el código fuente, las plantillas del servidor, los fragmentos del gestor de etiquetas y package.json:
  1. Encuentra cualquier superficie de v2 que ya exista: grep -rnE "SdkPayments\.initialize|\.transaction\(|\.start\(\{|getPaymentMethodsViews|transactionStatus|\.antifraud\(|onStatus|saveCardEnabled|showStatusScreen|sdk-web\.[a-z.]*y\.uno/v2". Un repositorio con ambas está en plena migración: reporta los restos de v1 en cada página que carga el script de v2. En tiempo de ejecución, typeof sdk.transaction === 'function' indica v2; una instancia de v1 tiene startCheckout y no tiene transaction.
  2. Clasifica cada flujo (Lite, Full, Seamless, Seamless Lite, botones externos, headless, Secure Fields, inscripción, fraude, pantalla de estado) como manual (el comercio crea el pago) o gestionado (el SDK lo crea).
  3. Mapea cada coincidencia con la tabla de abajo, ejecuta las verificaciones M1 a M25 y escribe el reporte.

Mapeo

Las secciones siguen la tabla de investigación 3.A a 3.H. Tipo: KEEP, RENAME, MOVE, BEHAVIOUR, NEW REQUIRED, REMOVED (sin reemplazo), SILENT (v2 acepta e ignora la clave anterior), BLOCKED (brecha de paridad: reporta “bloqueado: brecha de paridad, no migres este flujo todavía”, no como un cambio).

3.A Arranque y globales

3.B Puntos de entrada y modos de flujo

3.C Nombres de opciones y callbacks

3.D Comportamiento obligatorio o nuevo

3.E CSS, DOM y marca blanca

3.F Opción card y configuración anidada

3.G Comportamiento que difiere y es fácil de pasar por alto

3.H Funcionalidades en v1 que no existen en v2 (BLOCKED: brecha de paridad)

Verificaciones

Reporta cada una como PASS / FAIL / N/A con archivo:línea y cita la línea. Cada título termina con el id de verificación de la investigación y una severidad: B bloqueante (sin pago o sin resultado), H alta (funcionalidad perdida en silencio o resultado incorrecto), M media (experiencia degradada), L baja (higiene), P brecha de paridad (repórtala como bloqueada, nunca como un cambio por hacer).

  1. Global y evento ready (M1, B)

Busca: window.Yuno, Yuno.initialize, yuno-sdk-ready. Sigue en v1: cualquier coincidencia. Cambio: window.SdkPayments, sdk-payments-ready, revisa el global antes de escuchar. Síntoma: Yuno is not defined, la inicialización nunca se ejecuta.

  1. URL del script y loader (M2, B)

Busca: etiquetas script, loadScript, sdk-static-bundles-ms. Sigue en v1: /v1.11/, loadScript() sin baseUrl, sri: true; también incorrecto: /v2/, /v2.2/. Cambio: URL completa v2.x.y; en las páginas de la UE, verifica que el host de la UE tenga la versión. Las versiones fijadas de v2 más antiguas, como v2.0.0, son válidas si la integración se probó con esa versión. Síntoma: sdk.transaction is not a function, o 404.

  1. Puntos de entrada de v1 (M3, B)

Busca: el segundo grep. Sigue en v1: cualquier llamada. Cambio: según el Mapeo; las filas REMOVED indican “sin reemplazo”. Síntoma: yuno.startCheckout is not a function.

  1. Modo y workflow de la sesión (M4, B)

Busca: el modo de v1 (Seamless = gestionado; startCheckout con yunoCreatePayment = manual) y el cuerpo de POST /v1/checkout/sessions del backend. Cambio: el modo gestionado no tiene createPayment y usa workflow: "SDK_SEAMLESS"; el modo manual tiene createPayment y el workflow por defecto. Síntoma: onStatus INTERNAL_ERROR.

  1. Firma de createPayment (M5, B)

Busca: (yuno)?[cC]reatePayment, continuePayment. Sigue en v1: dos o tres parámetros, el primero usado como string, la sesión de la configuración en uso, continuePayment(), notifyError(). Cambio: un solo token; envía token.token y token.checkout_session; devuelve una Promise que se resuelva en todas las rutas; rechaza ante un fallo. Renombra yunoCreatePayment: el código 2.2.0 mantiene un alias, pero la selección del modo lee solo createPayment (verifica en tiempo de ejecución). Síntoma: Create Payment 4xx, pago con sesión obsoleta, formulario atascado.

  1. Callbacks de resultado y estados (M6, B)

Busca: yunoPaymentResult, paymentResult, yunoError, enrollmentStatus, los strings de estado de v1. Cambio: un solo onStatus(result) sobre los estados del backend más INTERNAL_ERROR y USER_CANCEL; los códigos de error del SDK (FORM_INVALID, MERCHANT_CREATE_PAYMENT_FAILED, ELEMENT_NOT_FOUND) están en message.code y substatus es null, por lo que nunca ramifiques según substatus para ellos; FORM_INVALID y los rechazos reintentables no son finales. Síntoma: no se maneja ningún resultado, la consola advierte ...created without an onStatus function....

  1. Modelo de renderizado (M7, H)

Busca: renderMode, viewContainer, CSS de overlay. Cambio: un contenedor con tamaño y elementSelector en transaction(). Síntoma: formulario en línea en lugar de modal; Wrong element selector. Bloqueado si el comercio requiere un modal.

  1. Opción de pantalla de estado (M8, H)

Busca: showPaymentStatus. Cambio: showStatusScreen. Síntoma: la pantalla de resultado del SDK se muestra de todos modos y onStatus espera a que el comprador la cierre. El changelog público de v2.1.0 todavía dice showPaymentStatus (desfase de la documentación).

  1. Carga (M9, M)

Busca: onLoading, showLoading, showLoader, hideLoader. Cambio: showLoading: (isLoading) => void, elimina type; un booleano debe desaparecer. Síntoma: un onLoading que se mantiene sigue ejecutándose, por lo que nada se rompe hasta que ambos están definidos; showLoading: true lanza un TypeError minificado; showLoading: false muestra en silencio el loader del SDK. Bloqueado donde el loader se maneja a mano con showLoader/hideLoader.

  1. Selección de la lista y pago (M10, B)

Busca: paymentMethodSelected, startPayment, mountCheckout. Cambio: getPaymentMethodsViews, guarda onPaymentSelected, el botón de pago llama a start({paymentMethod: selected}), ignora selectionSource: 'auto'. Síntoma: la lista se muestra y nada se paga.

  1. Botones externos (M11, H)

Busca: mount(Seamless)?ExternalButtons, unmount*ExternalButton*. Cambio: un mount de vista por wallet, con await o con catch. Síntoma: falta una wallet, rechazo no manejado. La familia no seamless está bloqueada.

  1. Claves de card (M12, H)

Busca: cardSaveEnable, requiredFieldsOrderedEnabled, type: 'step'. Cambio: saveCardEnabled; elimina la otra. Síntoma: la casilla para guardar la tarjeta desaparece en silencio. 'step' está bloqueado.

  1. Opciones eliminadas (M13, H)

Busca: onlyExpressPaymentMethods, stickyPayButton, __internal, renderMode. Cambio: reporta cada una; decide con el comercio. Síntoma: falta comportamiento en silencio. onLoading no está en esta lista: todavía se llama (M9). Los elementos con brecha de paridad están bloqueados.

  1. Secure Fields (M14, B)

Busca: secureFields(, .render(, generateToken*, enableV2, enableMultiplesCard. Cambio: tx.secureFields(), .mount, paga con start y solo claves no PCI en data.card (holderName, type, installment, customer, vaultOnSuccess); condiciona el pago a !error && isDirty. Síntoma: render is not a function, error por claves PCI.

  1. Headless (M15, B)

Busca: apiClientPayment, generateToken, getThreeDSecureChallenge, payment_method.card.detail, holder_name. Cambio: data.card en camelCase más createPayment; elimina el código de 3DS; un solo start() headless por transacción. Síntoma: error de tokenización, campos vacíos.

  1. Inscripción (M16, B)

Busca: mountEnrollmentLite, apiClientEnroll, continueEnrollment, vaultedToken en los callbacks. Cambio: transaction({customerSession}).start(...); el éxito es ENROLLED (UI) o CREATED (headless); el token almacenado (vaulted) viene del backend. Síntoma: se guarda un token undefined.

  1. Fraude y pantalla de estado (M17, H)

Busca: executeFraudCheck, mountFraud, mountStatusPayment. Cambio: executeFraudCheck pasa a ser sdk.antifraud, verificado con status === 'success'; mountFraud es una interfaz de pago con tarjeta, por lo que pasa a ser un transaction({...}) normal más start({paymentMethod:{type:'CARD'}}), con su yunoCreatePayment movido a createPayment(token), según la página pública de migración de fraude; transactionStatus con elementSelector. Síntoma: se envían fingerprints indefinidos; not a function; eliminar mountFraud quita un flujo de pago.

  1. Llamadas de utilidad (M18, H)

Busca: isPaymentMethodAvailable, updateCheckoutSession, refreshPromotionQuote, unmountSdk en la instancia. Cambio: muévelas a la transacción; mantén clearApiCache, setCanaryMode. Síntoma: ... is not a function.

  1. Ciclo de vida de initialize (M19, H)

Busca: dónde y con qué frecuencia se ejecuta initialize (cuerpos de render, efectos, por checkout, applicationSession cambiante). Cambio: una instancia por página con argumentos estables, una transacción por checkout. Síntoma: This SdkPayments instance is no longer active: a later initialize() replaced it... y el formulario desaparece. Dos llamadas sobre una instancia reemplazada no lanzan error: antifraud() se resuelve con {status:'error'} e isPaymentMethodAvailable() se resuelve con false.

  1. Desmontaje (M20, M)

Busca: unmountSdk(, limpiezas de efectos. Cambio: await tx.unmount(); trata el USER_CANCEL que entrega como desmontaje, no como abandono. Síntoma: pantalla de error al navegar. Los remontajes de React StrictMode no se han probado en v2: verifica en tiempo de ejecución.

  1. Reintento (M21, H)

Busca: isRetrying, newCheckoutSession, código de reintento personalizado. Cambio: el modo manual mantiene el formulario después de un rechazo reintentable (sesión en token.checkout_session); después de un resultado final, sesión nueva y transacción nueva. Síntoma: reintento roto; The payment on this checkout session already finished....

  1. CSS, DOM, marca blanca (M22, M)

Busca: selectores CSS y JS sobre nombres de clase y atributos del SDK. Sigue en v1: un selector sobre un nombre de v1.11 que v2 no renderiza. Excepción: yuno-container-spinner-content, yuno-container-spinner-ring y data-yuno-placeholder, que v2 sí renderiza. Cambio: mantén sdk-payments-; vuelve a revisar visualmente cada override (solo se compararon tres clases); dale un id a un contenedor HTMLElement, o v2 agrega yuno-view-<random>. Una página de marca blanca en v2 siempre contiene los nombres yuno del spinner; repórtalo como una nota, no como un fallo. Síntoma: estilos perdidos.

  1. Tipos de TypeScript (M23, L)

Busca: @yuno-payments/sdk-web-types, tipos YunoSDK. Cambio: una declaración local de v2 escrita a partir de las páginas públicas de migración a v2. Síntoma: errores de compilación o any silencioso.

  1. Revisión de brechas de paridad (M24, P)

Busca: cada fila BLOCKED. Reporta el flujo como “bloqueado: brecha de paridad, no migres este flujo todavía” y mantenlo en v1.11. Pide a tu contacto en Yuno la lista actual de brechas de paridad y contrástala.

  1. Despliegue y reversión (M25, M)

Busca: un flag o un interruptor por entorno para la URL del script. Cambio: conserva la ruta de v1.11, despliega v2 mediante un flag, prueba primero en sandbox. Síntoma: no hay vuelta atrás.

Formato del reporte

Una línea por hallazgo: severidad, verificación, archivo:línea, el cambio en una línea. Termina con las versiones de los scripts de v1 y v2 encontradas y si el repositorio es solo v1 o mixto.

Diagnósticos por capturar

  1. La URL del script realmente cargado (pestaña Network) y el valor de typeof sdk.transaction (function solo en v2).
  2. El id de la sesión de checkout, su workflow y la hora UTC del intento.
  3. Cada payload de onStatus recibido (status, substatus, message.code, message.reason).
  4. Las líneas de consola que empiezan con SdkPayments y cualquier mensaje lanzado por transaction(), start() o mount().
  5. La solicitud de createPayment que envió tu backend (campo del token y sesión, sin datos personales).

Verifica en tiempo de ejecución

Esto no se pudo confirmar leyendo código; pruébalo antes de depender de ello: qué hace un yunoCreatePayment suelto (firma de v1) una vez fusionado en createPayment; qué renderiza card.type: 'step'; transaction.unmount() bajo un remontaje de React StrictMode; la lista completa de clases CSS; la disponibilidad de v2.2.0 en la UE. Parte de esto se leyó de código de v2 no publicado, por lo que algunos comportamientos podrían no estar todavía en el bundle 2.2.0. Fuentes: el código fuente del Web SDK 1.11.47 y 2.2.0, el reporte de la API de v2, el loader de npm @yuno-payments/sdk-web, @yuno-payments/sdk-web-types y la documentación pública de Yuno (la pestaña “SDK”, sus guías de migración y changelog, y la página de marca blanca); pruebas de CDN. Fecha de la investigación: 2026-10-29.