Validate my Yuno Web SDK v2 integration following this fileFunciona como
CLAUDE.md, AGENTS.md o como un prompt pegado. Solo lee código y no cambia nada a menos que lo pidas.
Cubre la línea sdk-web v2 (“Yuno SDK 2.x”): window.SdkPayments, SdkPayments.initialize(...), y luego
sdk.transaction({...}). Consulta el changelog de Web SDK para ver la versión actual. Cada versión se sirve en una URL de
versión completa, como https://sdk-web.y.uno/v2.x.y/main.js, documentada en la pestaña “SDK” de docs.y.uno (docs/yuno-sdk/*;
la pestaña “SDKs” es 1.x). Los ejemplos de la documentación pública fijan v2.5.1.
Cómo usarlo
Primero confirma que el repositorio usa v2. Busca en el código fuente, las plantillas HTML, las plantillas del servidor ypackage.json:
- v2: una URL
/v2.<minor>.<patch>/main.js,sdk.transaction(...),transaction.start(...),getPaymentMethodsViews(...). - v1 (1.x):
/v1.11/main.js,window.Yuno,Yuno.initialize,startCheckout,startSeamlessCheckout,mountCheckoutLite,yunoPaymentResult. Detente y usa el validador de v1 o el de migración. - El nombre global no lo decide: desde 1.9.0, v1 también define
window.SdkPaymentsy disparasdk-payments-ready. v2 tienetypeof sdk.transaction === 'function'; v1 tienestartCheckouten su lugar.
El flujo que se valida
createPayment con un checkoutSession es manual; sin él, el SDK crea el pago (administrado,
sesión workflow: "SDK_SEAMLESS"). La inscripción siempre es administrada. No hay on() ni close().
Verificaciones
Carga e inicialización
1. El script es v2 y está fijado a una versión completa (V1, B)- Busca con grep
sdk-web\.(y\.uno|sandbox\.y\.uno|staging\.y\.uno|prod\.eu\.y\.uno)/[^"' ]*main\.js,sdk-static-bundles-ms/sdk-web/,loadScript(y@yuno-payments/sdk-web. - PASS: la URL coincide con
/v2\.\d+\.\d+/main.js, o con la URL SRI.../sdk-web/v2.<m>.<p>/main.js. - FAIL con
/v1.11/,/v2/,/v2.2/,latest; conloadScript()sinbaseUrl(carga/v1.11/); conloadScript({ sri: true })(una URL SRI de v1.11.x escrita a mano, la compilación 1.11 fijada por el paquete npm). Para npm, pasabaseUrl: 'https://sdk-web.y.uno/v2.x.y'. Las versiones v2 más antiguas, comov2.0.0, son válidas si la integración se probó con esa versión. - Por qué: un bundle v1 produce
sdk.transaction is not a function; las carpetas móviles/v2/,/v2.0/,/v2.2/devuelven 404. No existe una carpeta v2 móvil: las actualizaciones son manuales.
- Busca con grep
window\.Yuno|\bYuno\.initialize|new Yuno|yuno-sdk-ready|YunoSDK. FAIL ante cualquier coincidencia en código v2. - Por qué: v2 solo define
window.SdkPayments:Yuno is not defined, oyuno-sdk-readynunca se dispara.
- Busca con grep
sdk-payments-readyySdkPayments. PASS:if (window.SdkPayments) start(); else window.addEventListener('sdk-payments-ready', start), o unloadScriptcon await / una promesa de carga propia. - FAIL con un
addEventListenersin más (el evento se dispara una sola vez, al cargar), o coninitializeantes de que el script se ejecute. - Por qué: el checkout nunca inicia en las páginas donde el script se cargó primero;
SdkPayments is not defined.
initialize usa await, se ejecuta en el cliente y solo con la clave pública (V4, B)
- Busca con grep
SdkPayments\.initialize\(; verificaawaito.then; verifica que no esté en código de servidor (getServerSideProps, componentes de servidor, manejadores de ruta); verifica que no haya ninguna clave secreta privada en el código del front end. - FAIL si el resultado se usa sin
await, si se ejecuta en el servidor o si se incluye una clave privada en el bundle. - Por qué: devuelve
Promise<SdkPayments>:sdk.transaction is not a function; en un servidor,window is not defined.
initialize son estables y se reutiliza una sola instancia (V5, W)
- Busca
initializeen funciones de render, en efectos sin una caché a nivel de módulo, o con un argumento que cambia en cada llamada (applicationSessionpor checkout,Date.now(), valores aleatorios). - FAIL con más de un conjunto de argumentos distinto durante la vida de la página, o con un
initializepor transacción. - Por qué: los mismos argumentos devuelven la misma instancia y registran
SdkPayments.initialize() was called again with the same arguments. The existing instance was returned; the SDK was not re-initialized.(benigno). Argumentos distintos eliminan la instancia anterior y el formulario montado desaparece.transaction(),transactionStatus(),start(),submit()ysecureFields()sobre ella lanzanThis SdkPayments instance is no longer active: a later initialize() replaced it. Use the instance returned by the most recent initialize().Unantifraud()reemplazado resuelve{ status: 'error' }yisPaymentMethodAvailable()resuelvefalse, en silencio.
Configuración y resultado de la transacción
6. La configuración de la transacción es válida (V6, B)- Para cada llamada a
.transaction(. PASS: exactamente uno decheckoutSession/customerSession;countryCode;onStatuses una función;createPayment, si está presente, es una función. Los repositorios de TypeScript también deben pasarlanguageyshowStatusScreen(requeridos por el tipo aunque la documentación los llame opcionales). - Por qué, errores textuales:
Provide either `checkoutSession` or `customerSession`, not both.,A `checkoutSession` or `customerSession` is required.,`countryCode` is required.,`createPayment` must be a function when provided.SinonStatus, la consola advierteSdkPayments transaction() was created without an `onStatus` function. The payment result will not be delivered to your integration. Pass `onStatus` in the transaction config to receive the result. - Las claves desconocidas y las exclusivas de v1 pasan sin error. La mayoría nunca se leen, pero tres siguen actuando:
onLoadingse sigue llamando (verificación 19);paymentMethodSelected/yunoPaymentMethodSelectedse disparan en cada selección de la lista, así que junto aonPaymentSelectedcada selección llama dos veces al comercio;yunoCreatePaymentse combina encreatePayment. Marca cada clave que no esté en el tipo v2 y cada nombre de callback de v1.
onStatus maneja el contrato completo de estados (V7, B)
- Lee el manejador. PASS: lee
result.status,result.substatus,result.message; manejaINTERNAL_ERROR(ramifica pormessage.code;substatusesnullen los errores del SDK) yUSER_CANCEL; trataINTERNAL_ERRORconmessage.codeFORM_INVALIDoCOLLECT_FAILED, y en modo manual unDECLINED/ERRORreintentable, como no finales. - FAIL con valores de v1 (
'FAIL','REJECT','PROCESSING','READY'), dos argumentos posicionales, ramificar porsubstatuspara los códigos de error del SDK, una redirección o un cierre en cada llamada, o el pedido marcado como pagado en el cliente conSUCCEEDED. - Por qué: las ramas nunca coinciden, un primer rechazo termina el ciclo de reintentos, o los pedidos se entregan sin pago.
Con
showStatusScreen: true(valor predeterminado),onStatusse dispara cuando el comprador cierra la pantalla de resultado del SDK.
workflow de la sesión de checkout (V8, B)
- Front end: ¿está presente
createPayment? Backend: busca con grepcheckout/sessionsyworkflow. PASS:createPaymentcon una sesión de workflow predeterminado; sincreatePaymentconworkflow: "SDK_SEAMLESS". - Por qué: un desajuste termina en
onStatusINTERNAL_ERROR; el backend rechaza la creación del pago del SDK.
createPayment sigue el contrato de Promise con un argumento (V9, B)
- Busca con grep
createPayment\s*[:=(]. PASS: un parámetrotoken; envíatoken.tokenytoken.checkout_sessional backend del comercio; devuelve una Promise que se resuelve en todas las rutas; rechaza ante un fallo del backend. - FAIL con
(ott, info, cs); el argumento usado como cadena del token; elcheckoutSessionde la configuración usado en lugar detoken.checkout_session; uncatch {}que resuelve; una ruta que nunca se resuelve; una llamada acontinuePayment(). - Por qué: un objeto enviado como token produce un 4xx en Create Payment; la sesión rota tras un rechazo reintentable,
así que la de la configuración queda obsoleta; no existe tiempo de espera, así que una promesa colgada deja el formulario cargando para siempre. Un
rechazo termina en
INTERNAL_ERRORconmessage.codeMERCHANT_CREATE_PAYMENT_FAILED, con el formulario aún montado. - Verifica en tiempo de ejecución: el modo se elige solo a partir de
createPayment, así que una configuración con únicamente el nombre de v1yunoCreatePayment(combinado en el estado con la firma de tres argumentos de v1) puede ejecutarse en modo administrado, no manual.
autoContinuePayment: false es deliberado (V10, W)
- Busca con grep
autoContinuePayment. PASS: ausente, ofalsecon el estado a cargo del webhook y una nueva sesión para cualquierstart()posterior. - Por qué: con
false, el SDK no ejecuta consulta de estado, ni 3DS, nionStatusdespués de quecreatePaymentse resuelve, y reutilizar la sesión lanza el error “already finished” (verificación 18). PayPal clásico y la inscripción de PayPal ignoranfalse;paypalBraintreelo respeta.
Montaje y pago
11.elementSelector se resuelve al momento de la llamada (V11, B)
- Revisa
elementSelectoren la configuración de la transacción, en cada vista.mount({ elementSelector })y entransactionStatus. El nodo debe existir y estar conectado cuando se ejecutastart()/mount(). - Solo la configuración de la transacción (el formulario que monta
start(), y la inscripción) acepta una cadena o unHTMLElement. Los montajes de vistas ytransactionStatussolo aceptan una cadena. - FAIL con un
HTMLElementpasado a un montaje de vista o atransactionStatus; un nodo aún no renderizado, renderizado de forma condicional o desconectado; ningún selector para un pago con formulario. - Por qué, textual:
elementSelector=[object HTMLDivElement] is not valid(elemento en el montaje de la lista),elementSelector=undefined is not valid(start()del formulario sin selector),elementSelector "<sel>" was not found in the document.,elementSelector is detached from the document.,Element <sel> doesn't exist in the DOMcononStatusINTERNAL_ERRORymessage.codeELEMENT_NOT_FOUND.
start() usa await con manejo de errores y no indica que el pago se completó (V12, B)
- Busca con grep
\.start\(. PASS: dentro de try/catch o.catch;paymentMethod.typesiempre definido; resultado leído solo enonStatus. Elstart()de un formulario se resuelve cuando el formulario está en la página, no cuando se paga. - FAIL sin catch;
.start()sinpaymentMethoden un pago; interfaz de “éxito” después deawait start(); un segundostart()sobre el mismo formulario montado en lugar desubmit(). - Por qué, rechazos textuales:
`paymentMethod.type` is required for a payment transaction.,`start()` has already been called on this transaction. Call `submit()` to submit the form it mounted.,A payment is in progress on this transaction. Wait for it to settle before starting another payment method.Una pantalla de “pagado” antes de que el comprador pague es el síntoma visible para el comercio.
- Revisa
showPayButtony el manejador del clic. Formulario:showPayButton:false,await start({ paymentMethod }), luegotransaction.submit(). Lista: el botón llama astart({ paymentMethod: selected })con el valor guardado deonPaymentSelected;selectionSource === 'auto'(preselección del SDK) no lo habilita. - FAIL con
submit()antes de questart()se resuelva, o en una lista, una billetera o una inscripción; Pay habilitado conauto; el botón no deshabilitado mientras un pago está en curso; un callback de selección de v1 conservado junto aonPaymentSelected. - Por qué, textual:
`submit()` needs a form mounted by `start({ paymentMethod })`. Call `start()` first and wait for it to resolve.,`submit()` does not pay from the payment method list. Call `start({ paymentMethod })` with the selected method.,`submit()` cannot pay a wallet. The shopper pays by tapping the wallet button.,`submit()` found no form to submit: the form `start()` mounted is no longer on the page. Call `start({ paymentMethod })` again.Unsubmit()mientrasstart()aún está montando no lanza error: igual que un formulario inválido, entrega unINTERNAL_ERRORno final conmessage.codeFORM_INVALID.
- Busca con grep
getPaymentMethodsViewsy\.mount\(. PASS:typessolo entrepaymentMethodList,applePay,googlePay,samsungPay,paypal,paypalBraintree,revolutPay; solo se construyen las vistas solicitadas, así que una vista usada sin estar entypesestá protegida (?.o una comprobación); cadamountcon await o con.catch(tipadovoid, devuelve una Promise); las billeteras pagan al tocarlas, sinstart(). - FAIL con nombres de v1 (
GOOGLE_PAY),views.x.mountsin protección, sin catch, vistas en una transacción de inscripción. - Por qué:
Cannot read properties of undefined (reading 'mount'); rechazo no manejadoThere are not valid payment methods; error lanzado`getPaymentMethodsViews` is not available for enrollment transactions. Use `secureFields()` to collect card data.Las vistas de billeteras siguen montadas después detransaction.unmount(); no existe un desmontaje por vista. Verifica en tiempo de ejecución: una lista más billeteras desde una misma transacción.
- Busca con grep
data:\s*\{\s*card. PASS:data.card.{holderName, number, securityCode, expirationMonth, expirationYear}en camelCase; unstart()por transacción; los datos de la tarjeta nunca se registran ni se almacenan. Una tarjeta guardada con un CVV nuevo esvaultedTokenmásdata.card.securityCode. - FAIL con snake_case (
holder_name,security_code,payment_method.card.detail), un segundostart()headless (de un solo uso), odatamientras hay un formulario de lista en línea montado. - Por qué: la tokenización falla o los campos llegan vacíos;
`start()` has already been called on this transaction.
- Busca con grep
secureFields(,\.create\(,\.render\(,\.mount\(,generateToken,isFieldComplete. - PASS:
const fields = await transaction.secureFields({ installmentEnable? });fields.create({ name, options }).mount('#sel'); Pay condicionado a!error && isDirtypor campo; pago mediantetransaction.start({ paymentMethod: { type: 'CARD', data: { card: { holderName } } } }). - FAIL con
.render((v1),generateToken*ocontinuePayment,isFieldCompletecomo condición, claves PCI endata.card. - Por qué:
render is not a function; un error lanzado que empieza conSecure fields collect the card data inside the mounted iframesy continúa conremove <keys> from `paymentMethod.data.card`. Only non-PCI metadata (holderName, type, installment, customer, vaultOnSuccess) may be passed here.; un botón Pay deshabilitado para PAN cortos válidos.
- Busca con grep
customerSession. PASS: sincheckoutSession,createPayment,showPayButtonniautoContinuePaymentjunto a él;start()sin argumentos para la interfaz,start({ paymentMethod: { type, data } })para headless; el éxito esENROLLED(interfaz) oCREATED(headless y Secure Fields). - FAIL al leer
result.vaultedToken(nunca se entrega; obtenlo desde el servidor),submit()o vistas. - Por qué: se guarda un token de vault
undefined; errores lanzados`submit()` is not available for enrollment transactions.o`paymentMethod.type` is required for a headless enrollment.
Nuevo render y ciclo de vida del framework
18. Una instancia, una transacción por montaje, limpieza al desmontar, compatible con StrictMode (V18, B) Ningún documento de v2 cubre los frameworks; estas reglas se derivan del código. Los mismos argumentos deinitialize devuelven la misma
instancia. Un segundo start() de un formulario montado lanza un error a propósito (un efecto de React ejecutado dos veces una vez creó un
pago). Una nueva Transaction reinicia el estado compartido de la instancia, así que con dos transacciones activas gana el último montaje.
unmount() es asíncrono, entrega USER_CANCEL para un intento sin terminar y deja las billeteras. Las sesiones liquidadas son finales.
- Todos los frameworks:
initializedetrás de una promesa a nivel de módulo (o siempre con los mismos argumentos); unatransaction()por checkout montado, creada donde el contenedor ya existe; una superficie de tarjeta activa por página; una nueva sesión de checkout implica una nueva transacción. FAIL coninitializeotransaction()en el cuerpo de un render, o con dos transacciones montadas a la vez. - React: la transacción se guarda en un
useRefy se crea en eluseEffectque posee el contenedor;start()se ejecuta una vez por transacción (protégelo con la ref); la limpieza llama aawait transaction.unmount()y borra la ref; los callbacks (onStatus,createPayment) leen las props más recientes mediante una ref para que un nuevo render no reconstruya la transacción. Bajo StrictMode el efecto se ejecuta, se limpia y se ejecuta de nuevo: PASS solo si la segunda ejecución construye una transacción nueva después de la limpieza, nunca un segundostart()sobre la primera. FAIL constart()en un efecto sin limpieza, o con dependencias del efecto que cambian en cada render. - Next.js: el código del SDK se ejecuta solo en el navegador: un componente
'use client'que llama ainitializedentro de un efecto, o un componente cargado condynamic(..., { ssr: false }). FAIL conSdkPaymentsen un componente de servidor,getServerSideProps, un manejador de ruta, o el nivel superior del módulo de un archivo renderizado en el servidor. - Vue y Angular (guía): crea la transacción en
onMounted/ngAfterViewInit, desmóntala enonBeforeUnmount/ngOnDestroy, y mantenla fuera del estado reactivo (shallowRefo una variable simple). - Desmontaje en SPA: al salir de la ruta del checkout se llama a
await transaction.unmount(); elUSER_CANCELque entrega no se muestra como error ni se trata como abandono; los contenedores de billeteras se eliminan junto con la ruta. - Por qué: formularios duplicados o que desaparecen, intentos de pago dobles,
`start()` has already been called on this transaction.,The payment on this checkout session already finished. Create a new checkout session and transaction to pay again., o un banner de error en cada cambio de ruta. - Verifica en tiempo de ejecución:
transaction.unmount()lee la raíz compartida después de sus await, y ninguna prueba cubre un remontaje con StrictMode. Reporta los hallazgos de StrictMode como “unverified against a real remount”.
Opciones y casos límite
19.showLoading es una función y el comercio es dueño del loader (V19, W)
- Busca con grep
showLoadingyonLoading. PASS:showLoading: (isLoading) => voidque muestra y oculta el loader del comercio; un manejador registrado reemplaza la superposición del SDK. - FAIL con
showLoading: true|false, cononLoading(nombre de v1, que v2 aún llama con el payload{ isLoading, type }de v1, junto a la superposición del SDK), o con un manejador sin interfaz detrás. - Por qué:
showLoading: truelanza un TypeError en el primer cambio de carga, nombrando una variable minificada, noshowLoading.showLoading: falsese trata como si no hubiera manejador: la superposición del SDK vuelve en silencio.
- Busca con grep
showPaymentStatus|showStatusScreen|transactionStatus. PASS:showStatusScreen;transactionStatusrecibeelementSelector(requerido). FAIL conshowPaymentStatus(se ignora, la pantalla de resultado se sigue mostrando). - Por qué: interfaz de resultado duplicada, y
onStatusretrasado hasta que el comprador cierra la pantalla del SDK.
- Busca con grep
card:\s*\{. PASS:saveCardEnabled,styles,type,vaultOnSuccess,texts,documentEnable,isCreditCardProcessingOnly,fonts. FAIL concardSaveEnableorequiredFieldsOrderedEnabled. - Por qué:
cardSaveEnablese ignora en silencio y la casilla de guardar tarjeta desaparece. ReportaexternalButtons.applePay.topLevelDomaincomo ignorado (I): v2 detecta por sí mismo el dominio de Apple Pay.
- Busca con grep
\.antifraud\(. PASS: compruebaresult.status === 'success'antes de usarresult.deviceFingerprints. FAIL sin comprobación, o si depende de un rechazo (nunca rechaza). Por qué: se envían huellasundefined.
- Ejecuta siempre esta parte: busca con grep en cada hoja de estilos y estilo de componente (
*.css,*.scss,*.less, bloques de estilo en*.ts,*.tsx,*.vue,*.svelte)yuno-yYuno-. Luego revisaapiUrl,assetUrl, los encabezados CSP y las reglas de proxy, cuando existan. - Las clases de formulario del SDK son
sdk-payments-*en v1.11 y v2; las pocas cadenasyuno-*que quedan en v1.11 son ids, nombres de eventos, nombres de chunks y el respaldo de fuenteYuno-Inter(el mapa de renombrado las lista como sin cambios), no clases de elementos. v2 renderizayuno-container-spinner-contentyyuno-container-spinner-ring(el spinner de cada montaje), además de<style id="yuno-container-spinner-style">ydata-yuno-placeholder. Los selectores sobre ellos son legítimos. - PASS: las sobrescrituras apuntan a
sdk-payments-*o a las dos clases del spinner; un proxy reenvía/sdk-static-bundles-ms/*;apiUrlyassetUrldefinidos juntos; el host de v2 está enscript-srcde CSP; en una página de marca blanca, un selectorHTMLElementtiene su propioid(los nombres del spinner siempre permanecen en el DOM). - FAIL con cualquier otro selector
yuno-/Yuno-(no coincide con nada que renderice el SDK), un host faltante en CSP, o un elemento sin id en una página de marca blanca. - Por qué: las sobrescrituras dejan de aplicarse, el script se bloquea, o el SDK asigna
yuno-view-<random>como id. Verifica en tiempo de ejecución: solo se compararon tres nombres de clase con v1, así que revisa cada sobrescritura visualmente.
Lado del servidor
24. El cumplimiento se confirma en el servidor y los tipos de TypeScript son los de v2 (V24, B)- Encuentra el manejador de webhook o la verificación
GET /v1/payments/...que dispara el cumplimiento, y cualquier.d.tsdewindow.SdkPayments. PASS: cumplimiento a partir del webhook o deGET payment; un.d.tslocal copiado del informe de la API de v2. - FAIL con cumplimiento desde
onStatus(pedidos pagados sin un pago), o@yuno-payments/sdk-web-typespara llamadas v2 (forma de v1, sintransaction: errores de compilación oanysilencioso; solo esta parte es (W)).
Formato del reporte
Diagnósticos que debes capturar
- La URL del script servido,
typeof sdk.transaction, el id de la sesión de checkout, suworkflow, la hora UTC. - Cada payload de
onStatusrecibido (status,substatus,message.code,message.reason). - Advertencias y errores de consola del SDK, citados textualmente (initialize, reemplazada, falta onStatus).
- La solicitud y la respuesta de Create Payment (sin datos de tarjeta), el framework, StrictMode, cambio de ruta o nuevo render.