Validate my Yuno VTEX headless wallet integration following CLAUDE.md.Audita la app contra el contrato de preflight diferido para billeteras en VTEX headless (Google Pay, Apple Pay, Click to Pay), descrito en el flujo siguiente, e informa qué está mal, con archivo y línea. Solo lee código; no cambia nada a menos que se lo pidas. SDK:
@yuno-payments/yuno-sdk-react-native (docs).
La integración que se usa aquí es el Lite SDK (startPaymentLite), no Full Checkout, Seamless ni Headless.
El flujo que se valida
/session/preflight/payments haya
almacenado el cuerpo con el token. El pago no existe en Yuno hasta el paso 8, por lo que onPaymentStatus nunca
informa un resultado de pago en este flujo. El resultado proviene de VTEX (verificación 17).
Los endpoints están en el host de la tienda VTEX: https://<store-host>/_v/<connector-app>/v4.
Verificaciones
Informa cada una como PASS / FAIL / N/A con la evidencia (archivo:línea). No asumas que una verificación pasa porque el código “se ve bien”: cita la línea que lo demuestra.
- El traspaso ocurre solo después del OTT
El defecto más común. /session/preflight/payments debe llamarse desde dentro del callback
onOneTimeToken (o onOneTimeTokenInfo), con un token no vacío, nunca antes de
startPaymentLite ni con un temporizador.
- Busca la suscripción a
YunoSdk.onOneTimeToken/onOneTimeTokenInfo(o el llamador deYunoSdk.startPaymentLite) y sigue hacia dónde va el token. - FAIL si la llamada a preflight-payments es alcanzable sin un token, envía
token: ''/null/undefined, o se ejecuta justo después deawait YunoSdk.startPaymentLite(...). Esa promesa se resuelve cuando la billetera inicia, no cuando termina; nunca lleva el token. - FAIL si la orden de VTEX (pasos 6 a 8) puede crearse antes de que el traspaso devuelva
{ deferred: true }, o si el token se envía a/payments/yuno(la ruta de la Payment App) en lugar de/session/preflight/payments. - FAIL si el traspaso puede ejecutarse dos veces para un mismo intento. El SDK conecta dos callbacks nativos al mismo
evento
YunoOneTimeToken, por lo que el evento puede llegar más de una vez con el mismo token, y suscribirse aonOneTimeTokeny aonOneTimeTokenInfolo duplica de nuevo. Protégelo (una referencia que guarde el token ya traspasado) para que la orden se cree una sola vez. - Por qué: el conector acepta un cuerpo sin token y responde
{ deferred: true }; el fallo solo aparece en la autorización, como una orden denegada conDeferred preflight payment creation failed. Una app que crea la orden primero, envía un traspaso sin token y luego publica el token en/payments/yunopuede completar un pago, pero solo mientras la autorización llegue antes del traspaso; el día que llegue después, el conector usa el cuerpo sin token y la orden se deniega.
createPaymentInAuth: true
Debe estar en el cuerpo de createPaymentInAuth: true/session/preflight/payments. Sin él, el pago se crea de inmediato, antes de que exista una
orden de VTEX.
- El SDK se inicializa exactamente con la clave que devolvió preflight
YunoSdk.initialize({ apiKey, countryCode })debe recibir lapublicApiKeyde esa misma respuesta de preflight.- Busca todos los puntos de inicialización, JavaScript y nativos:
grep -rnE "YunoSdk\.initialize|YunoSdkModule\.initialize|Yuno\.initialize|markAsInitialized" --include='*.ts' --include='*.tsx' --include='*.js' --include='*.kt' --include='*.java' --include='*.swift' --exclude-dir=node_modules --exclude-dir=Pods --exclude-dir=.git --exclude-dir=build . - La primera inicialización del proceso es la que cuenta. En Android esto es seguro: una vez inicializado el
SDK,
YunoSdk.initializedesde JavaScript regresa sin tocar el SDK nativo, por lo que una llamada posterior con la clave de preflight no cambia nada. Trata iOS de la misma manera. - FAIL si encuentras: una clave codificada en
App.tsx, una clave de.env/ configuración remota / build flavor, oYunoSdkModule.initialize(this, "<key>")enMainApplication.onCreate(), a menos que se demuestre que ese valor es la misma clave que preflight devuelve para esta tienda y este entorno. La guía de configuración del SDK pide esa llamada nativa, por lo que la mayoría de las apps Android la tienen: informa el prefijo de entorno de la clave (sandbox_,prod_, nunca el valor completo) junto al prefijo de la clave que devuelve preflight. - FAIL si la tienda usa más de una afiliación de Yuno (preflight llamado con
affiliationName) y la app espera cambiar de clave entre órdenes: la segunda clave se ignora hasta que la app se reinicia. La verificación 4 indica qué nombre debe enviar cada llamada. - Una clave obsoleta hace que las primeras llamadas de la sesión fallen con 401 y la billetera se cierre sin ningún mensaje.
- Ambas llamadas de preflight nombran la afiliación de producción
Aplica al conector de VTEX 4.2.378 y posteriores. affiliationName es opcional en los cuerpos de
/session/preflight (orderFormId, amount, currency, country, affiliationName) y de
/session/preflight/payments (orderFormId, payment, affiliationName, createPaymentInAuth), pero la
app debe enviarlo en ambas.
- Sin él, o con una cadena vacía, el conector toma la primera afiliación de la tienda cuyo nombre de
implementación contiene “Yuno” (en cualquier combinación de mayúsculas y minúsculas), en el orden en que VTEX las lista. Una afiliación de VTEX no lleva indicador de prueba ni de producción, por lo que una
afiliación de prueba (estado “Teste” en el admin de VTEX) listada antes que la de producción es la que se usa. La sesión
se abre entonces con las credenciales de la afiliación de prueba y falla cuando no son válidas para producción
(por ejemplo, un Account ID que no existe), y preflight responde
500 {"error":"Failed to create preflight session"}. - Con un nombre, el conector busca una afiliación con exactamente ese nombre, con la misma ortografía y las mismas mayúsculas y minúsculas. Un nombre
que la tienda no tiene responde
404 {"error":"Yuno affiliation not found"}en ambas rutas. - El nombre es por tienda. La app debe conocer el nombre de la afiliación de Yuno de producción de cada tienda, tal como aparece en el admin de VTEX en Payments > Affiliations.
- Envía el mismo nombre en ambas llamadas. El pago queda vinculado a la sesión que abrió la primera llamada y a la cuenta de Yuno de la afiliación que resuelve la segunda llamada, por lo que dos nombres emparejan una sesión de una cuenta con otra cuenta.
- FAIL si alguna llamada omite
affiliationNameo envía'',nulloundefined. - FAIL si el nombre está codificado con un solo valor mientras la app atiende tiendas cuya afiliación de producción tiene un nombre diferente.
- FAIL si las dos llamadas pueden enviar nombres diferentes para una misma orden.
- Informa el valor enviado en cada llamada, de dónde lo lee la app y si la tienda tiene más de una afiliación del proveedor Yuno. Cuando el código no lo permita saber, indícalo y pide la lista de afiliaciones de la tienda.
- Síntoma: con la misma compilación de la app, el botón de la billetera falla en algunas tiendas y funciona en otras, preflight responde el 500 anterior y los pagos con tarjeta en las mismas tiendas funcionan. El mismo 500 también aparece cuando la búsqueda de afiliaciones de la tienda falla del lado de VTEX, sin importar el nombre que se envíe, por lo que un 500 por sí solo no demuestra un nombre incorrecto.
- El tipo de método de pago coincide con lo que VTEX autoriza
methodSelected.paymentMethodType y el payment_method.type del traspaso (APPLE_PAY / GOOGLE_PAY /
CLICK_TO_PAY) deben tener el mismo valor y corresponder al método de pago de VTEX con el que se crea la orden
(Apple Pay / Google Pay / C2P). Compara el paymentSystem usado en el paso 5 / paso 7 con el tipo enviado
en el traspaso. Una discrepancia hace que el conector ignore el pago almacenado.
- El monto, la moneda y el país son idénticos en preflight y en el traspaso
- El monto es un número JSON en unidades decimales (
845.90), no centavos (84590) ni una cadena. - La misma tripleta
amount:currency:countryva a ambas llamadas; se le calcula una huella. Una discrepancia da409. - FAIL si el monto se lee de una fuente diferente en las dos llamadas (por ejemplo, total del carrito frente a total de la orden), o si alguna llamada ocurre antes de que el total del carrito sea definitivo.
- El
countryCodeque se pasa aYunoSdk.initializey astartPaymentLitees ese mismo país. FAIL si es una constante mientras la tienda vende en más de un país.
- El total se fija antes de preflight y el flujo se reinicia si cambia
El envío, los cupones y las cuotas deben resolverse todos antes de /session/preflight. Si el total cambia después,
la app debe volver a ejecutar desde preflight e iniciar la billetera con el nuevo checkoutSession. FAIL si el código puede
cambiar el carrito mientras hay una sesión activa sin recrearla.
- Un host de tienda por orden
Preflight, preflight/payments y la creación de la orden deben usar el mismo host de cuenta de VTEX. FAIL si la URL base del conector
y la URL base del checkout apuntan a cuentas diferentes.
showPaymentStatus está desactivado
showPaymentStatus está desactivadostartPaymentLite({ ..., showPaymentStatus: false }). Su valor predeterminado es true cuando se omite, así que FAIL si el campo
falta. El resultado vive en la orden de VTEX, no en la pantalla del SDK (verificación 17).
- Los listeners se suscriben antes de que inicie la billetera y permanecen suscritos
El token llega como un evento nativo. Una suscripción que no existe en ese instante pierde el evento: en iOS
nada almacena el token, por lo que se pierde.
- FAIL si
onOneTimeTokense suscribe después destartPaymentLite, dentro del mismo handler que inicia la billetera, o en un componente que puede desmontarse mientras la hoja de la billetera está abierta (un modal o bottom sheet, una pantalla que navega a otra). - FAIL si una suscripción nunca se elimina (
subscription.remove()en la limpieza del efecto): una pantalla montada dos veces realiza entonces el traspaso dos veces. - Solo Android:
YunoSdk.getLastOneTimeToken()devuelve el token del intento actual cuando el evento se emitió mientras JavaScript estaba en pausa (se borra cuando iniciastartPaymentLite). Leerlo cuando la app vuelve al primer plano sin un token es una recuperación válida. En iOS siempre devuelvenull.
state.status como cadena y maneja ambas grafías: las plataformas no
emiten los mismos valores (iOS CANCELLED_BY_USER / PROCESSING / INTERNAL_ERROR, Android CANCELLED /
PENDING / ERROR), y el enum YunoStatus solo lista los de iOS. FAIL si el cierre de la hoja de la billetera se
detecta únicamente con YunoStatus.CANCELLED_BY_USER.
- Las órdenes divididas no se ofrecen con billeteras
Un carrito cumplido por más de un vendedor se convierte en varias órdenes de VTEX, y un token de billetera no puede cubrirlas.
FAIL si se ofrecen billeteras sin comprobar que el carrito puede producir una sola orden.
- Cuotas (solo si se ofrecen, Apple Pay / Google Pay)
/installments/apmse llama después de preflight, con elcheckoutSession+publicApiKeyde esa sesión, una vez por billetera, concountryy unlocalecompleto (pt-BR).- La cantidad elegida viaja como
payment_method.detail.card.installmentsen el cuerpo del traspaso, nunca conCLICK_TO_PAY, y el monto sigue siendo el total de la orden. - Una lista vacía, un error o un tiempo de espera agotado deben dejar sin selector y permitir que la billetera continúe. FAIL si el checkout se bloquea por esta llamada.
- Configuración nativa
- La app no se ejecuta en Expo Go: el SDK es un módulo nativo y necesita una development build o un proyecto bare.
Informa cómo se generan los proyectos nativos (bare,
expo prebuild, EAS). - Android:
- el repositorio Maven de Yuno (
https://yunopayments.jfrog.io/artifactory/snapshots-libs-release) está en los repositorios a nivel de proyecto; minSdkVersion21+,compileSdkVersion35+, Java 17, Kotlin 1.9.24+. Informa la versión de Kotlin: el módulo del SDK usa Jetpack Compose con la extensión del compilador para Kotlin 1.9, por lo que con Kotlin 2.x informa si el módulo compila;YunoSdkModule.initialize(...)enMainApplication.onCreate()(su clave se evalúa en la verificación 3);YunoSdkModule.registerYunoCallbacks(this)enMainActivity.onCreate()antes desuper.onCreate(). Es lo que entrega los eventos de estado del pago en Android; sin ello, una hoja de billetera que el comprador cerró es invisible para la app. Informa si está presente.
- el repositorio Maven de Yuno (
- iOS:
platform :ios, '14.0'o superior en elPodfile, el archivo.entitlementsde la app tienecom.apple.developer.in-app-paymentscon el merchant ID registrado en Yuno para esta afiliación, y el App ID tiene la capacidad de Apple Pay. Informa el merchant ID encontrado para poder compararlo con el lado de Yuno. Con Expo, el entitlement proviene deios.entitlementsen la configuración de la app.
- Pruebas en compilaciones reales
Las billeteras no se pueden validar en un simulador/emulador ni en una compilación de depuración: Google Pay necesita el keystore de release
registrado en la Google Pay & Wallet Console, y Apple Pay una compilación firmada con el entitlement anterior.
FAIL si las instrucciones de prueba del repositorio dicen lo contrario.
- Versión del SDK
@yuno-payments/yuno-sdk-react-native en package.json. Informa la versión que resuelve el lockfile y las
versiones nativas que fija, ya que el comportamiento de las billeteras lo decide el SDK nativo, no la capa de JavaScript:
- Android:
com.yuno.payments:android-sdkennode_modules/@yuno-payments/yuno-sdk-react-native/android/build.gradle - iOS:
YunoSDKennode_modules/@yuno-payments/yuno-sdk-react-native/YunoSdkReactNative.podspec(YunoSdk.podspechasta 1.3.0), y la versión realmente instalada enios/Podfile.lock
FAIL si
Podfile.lock contiene un YunoSDK diferente del que fija el podspec (no se volvió a ejecutar pod install después de
la actualización).
- El SDK nativo llega al servicio de tokens (en ejecución, compilación firmada)
Nada en el código de la app puede demostrarlo: el token de un solo uso lo solicita el SDK nativo, no JavaScript.
Ejecuta un intento en una compilación firmada con el tráfico del dispositivo capturado (Proxyman / Charles con el iPhone o
el dispositivo Android por proxy, SSL proxying habilitado para *.y.uno), completa la hoja de la billetera e informa cuáles
de estas llamadas a la API de Yuno aparecen después de startPaymentLite, en orden:
- la llamada de configuración de la billetera: Apple Pay:
.../payments/transactions/APPLE_PAY(sesión de comercio); Google Pay: las llamadas de configuración/sdkantes de que se abra la hoja .../wallet/decrypt: el payload de la billetera regresó de la hoja y se entregó a Yuno- la llamada de creación del token (
.../tokeno.../one-time-token): el OTT existe
- Solo 1 → la hoja nunca devolvió un pago: discrepancia de entitlement / merchant ID (verificación 13) o el usuario canceló. No es un defecto del SDK.
- 1 y 2, sin 3 → el SDK nativo se detuvo entre decrypt y token. Informa el par de versiones (verificación 15).
- 1, 2 y 3, pero el listener no registró ningún token → el evento se emitió sin nadie suscrito (verificación 10). En
Android, lee
YunoSdk.getLastOneTimeToken()para confirmar que el token existió. - Las tres y el listener registró el token → el lado del SDK está bien; el problema está en el traspaso (verificación 1).
adb logcat | grep -i yuno, la consola de Xcode en iOS), y
enable_logs_ios / enable_logs_android en la cuenta de Yuno imprimen estas llamadas desde el SDK nativo, pero están
desactivados de forma predeterminada, por lo que la captura con proxy es la opción confiable. Nunca pegues la captura en un canal público:
los cuerpos de decrypt y de token contienen datos de tarjeta.
- El resultado se lee de VTEX, no del listener
Después del traspaso, la app no debe esperar onPaymentStatus: en este flujo no llega ningún resultado de pago. El
resultado proviene del paso 8 y de la orden:
Después de un 2xx,
GET /api/checkout/pub/orders/order-group/{orderGroup} y decide a partir del status de cada orden:
payment-approved (o cualquier estado posterior) es éxito, payment-pending significa que el pago aún se está
procesando.
- FAIL si la pantalla de éxito/fallo depende de
onPaymentStatus, decontinuePaymento del valor de retorno destartPaymentSeamlessLite, o si un 2xx se trata como aprobado sin leer la orden. - FAIL si la app no muestra nada entre el token y el resultado. El SDK cierra su UI una vez emitido el token
(
keepLoaderno tiene efecto en el SDK 1.4.0, yhideLoader()no hace nada en Android), por lo que el estado de progreso es propio de la app, y el botón de pago debe permanecer deshabilitado hasta que se conozca el resultado.
Formato del informe
Diagnósticos para capturar de una ejecución fallida en el dispositivo
Cuando las verificaciones pasan y la billetera aun así no se completa, captura y envía:- El
checkoutSessionde la respuesta de preflight, elaffiliationNameenviado en ambas llamadas de preflight y la marca de tiempo UTC del intento. - Cada línea del listener de la verificación 10, en orden, más las líneas de la consola nativa que mencionen Yuno. Los eventos de React Native llevan solo el estado; el subestado y el mensaje existen únicamente en los logs nativos.
- El modelo del dispositivo y la versión del sistema operativo, la compilación de la app (release/debug), la versión de React Native y la arquitectura (antigua / nueva), y las versiones del SDK de la verificación 15.
- Si apareció la hoja nativa de la billetera y qué mostró al cerrarse.
- El
orderGroupde VTEX, el estado HTTP y el cuerpo degatewayCallback, y el estado de la orden leído después.