Validate my Yuno VTEX headless wallet integration following CLAUDE.md.Audita la app según el contrato preflight diferido para wallets 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.
El flujo que se valida
/session/preflight/payments haya
almacenado el body con el token. El pago no existe en Yuno hasta el Paso 8, por lo que el listener del SDK nunca
informa un estado de pago en este flujo (status=null después del token es lo esperado). 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.
- La transferencia ocurre solo después del OTT
El defecto más común. /session/preflight/payments debe llamarse desde dentro del
callback del listener, con un token no vacío, nunca antes de startPaymentLite y nunca con un temporizador.
- Busca el
YunoPaymentListener(o quien llame aYuno.startPaymentLite) y sigue hacia dónde vastate.token. - FAIL si la llamada a preflight-payments es alcanzable sin un token, envía
token: ''/null, o se ejecuta en la misma función que llama astartPaymentLite, antes de cualquier evento. - FAIL si la orden de VTEX (Pasos 6–8) puede crearse antes de que la transferencia devuelva
{ deferred: true }, o si el token se envía a/payments/yuno(la ruta de la Payment App) en lugar de a/session/preflight/payments. - Por qué: el conector acepta un body 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 una transferencia sin token y luego publica el token en/payments/yunopuede completar un pago, pero solo mientras la autorización llegue antes que la transferencia; el día que llegue después, el conector usa el body sin token y la orden se deniega.
createPaymentInAuth: true
Debe estar en el body 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
Yuno.init(apiKey: …)debe recibir lapublicApiKeyde esa misma respuesta de preflight.- FAIL si: la clave está escrita en el código, proviene de
.env/configuración remota/build flavor, oYunoSdkAndroidPlugin.initSdk(...)en una claseApplicationusa una clave distinta. - Busca todos los puntos de inicialización:
grep -rn "Yuno.init\|initSdk\|YunoSDK.initialize" lib android ios. Cuando el SDK se inicializa más de una vez, el primero suele prevalecer en iOS: una clave obsoleta allí hace que las primeras llamadas de la sesión fallen con 401 y la wallet se cierre sin 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 bodies de ambos
/session/preflight (orderFormId, amount, currency, country, affiliationName) y
/session/preflight/payments (orderFormId, payment, affiliationName, createPaymentInAuth), pero la
app debe enviarlo en ambos.
- 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 tiene indicador de prueba o 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 mayú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, por lo que dos nombres emparejan una sesión de una cuenta con otra cuenta.
- FAIL si alguna de las llamadas omite
affiliationNameo envía''onull. - FAIL si el nombre está fijo en un único valor mientras la app atiende tiendas cuya afiliación de producción tiene un nombre distinto.
- FAIL si las dos llamadas pueden enviar nombres distintos 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, dilo y pide la lista de afiliaciones de la tienda.
- Síntoma: con la misma build de la app, el botón de la wallet 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 qué nombre 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
payment_method.type (APPLE_PAY / GOOGLE_PAY / CLICK_TO_PAY) debe corresponder al método de pago de VTEX
con el que se crea la orden (Apple Pay / Google Pay / C2P). Revisa el paymentSystem usado en el Paso 5 /
Paso 7 contra el tipo enviado en la transferencia. 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 la transferencia
- El monto es un número JSON en unidades decimales (
845.90), no en centavos (84590) y no una cadena. - La misma terna
amount:currency:countryva a ambas llamadas; se le calcula una huella (fingerprint). Una discrepancia es un409. - FAIL si el monto se lee de una fuente distinta en las dos llamadas (por ejemplo, total del carrito vs total de la orden), o si alguna de las llamadas ocurre antes de que el total del carrito sea definitivo.
- 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 desmontar el SDK y volver a ejecutar desde preflight con la nueva sesión. 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 distintas.
showPaymentStatus está desactivado
showPaymentStatus está desactivadostartPaymentLite(..., showPaymentStatus: false). El resultado vive en la orden de VTEX, no en la pantalla del SDK
(verificación 17).
- El listener se monta antes de que inicie la wallet y permanece montado
YunoPaymentListener debe envolver un widget que esté activo durante todo el flujo. FAIL si se crea dentro de un
diálogo/bottom sheet que la hoja de la wallet pueda eliminar, o si startPaymentLite puede ejecutarse antes de que el widget
esté construido. Registra cada evento, no solo el token:
state.substatus y state.message requieren yuno >= 1.0.19 y son lo que debe incluir un ticket de soporte.
- Las órdenes divididas no se ofrecen con wallets
Un carrito atendido por más de un vendedor se convierte en varias órdenes de VTEX, y un token de wallet no puede cubrirlas.
FAIL si se ofrecen wallets sin comprobar que el carrito pueda producir una única 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 wallet, concountryy unlocalecompleto (pt-BR).- El número elegido de cuotas viaja como
payment_method.detail.card.installmentsen el body de la transferencia, nunca conCLICK_TO_PAY, y el monto sigue siendo el total de la orden. - Una lista vacía, un error o un timeout deben dejar sin selector y permitir que la wallet continúe. FAIL si el checkout se bloquea por esta llamada.
- Configuración nativa
- Android:
MainActivityextiendeFlutterFragmentActivity; el repositorio Maven de Yuno está enallprojects; en Kotlin 2.x se aplica el plugin del compilador de Compose (extra["kotlin_version"]definido para que el plugin lo detecte) y elcompileSdkdel módulo:yunoes 35 o superior. - iOS: deployment target 14 o superior,
ios/Runner/Runner.entitlementstienecom.apple.developer.in-app-paymentscon el ID de comercio registrado en Yuno para esta afiliación, y el App ID tiene la capacidad de Apple Pay. Informa el ID de comercio encontrado para poder compararlo con el lado de Yuno.
- Pruebas en builds reales
Las wallets no se pueden validar en un simulador/emulador ni en una build de debug: Google Pay necesita el keystore de release
registrado en la Google Pay & Wallet Console, y Apple Pay una build firmada con el entitlement anterior.
FAIL si las instrucciones de prueba del repositorio dicen lo contrario.
- Versión del SDK
yuno en pubspec.yaml. Informa la versión resuelta y las versiones nativas que fija
(~/.pub-cache/hosted/pub.dev/yuno-<v>/android/build.gradle e ios/yuno.podspec), ya que el comportamiento de las wallets
lo decide el SDK nativo, no la capa Dart.
- El SDK nativo llega al servicio de tokens (en ejecución, build firmada)
Nada en el código de la app puede demostrarlo: el token de un solo uso lo solicita el SDK nativo, no Dart.
Ejecuta un intento en una build firmada con el tráfico del dispositivo capturado (Proxyman / Charles con el iPhone o
el dispositivo Android conectado por proxy, con SSL proxying habilitado para *.y.uno), completa la hoja de la wallet 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 wallet: Apple Pay:
.../payments/transactions/APPLE_PAY(sesión de comercio); Google Pay: las llamadas de config/sdkantes de que se abra la hoja .../wallet/decrypt: el payload de la wallet volvió 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 / ID de comercio (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 el token. Informa el par de versiones (verificación 15).
- 1, 2 y 3, pero el listener no registró ningún token (verificación 10) → el MethodChannel del plugin lo perdió.
- Las tres y el listener registró el token → el lado del SDK está bien; el problema está en la transferencia (verificación 1).
enable_logs_ios / enable_logs_android en la cuenta de Yuno también imprimen estas llamadas desde el SDK, pero están
desactivados por defecto, por lo que la captura con proxy es la opción confiable. Nunca pegues la captura en un canal público:
los bodies de decrypt y del token contienen datos de tarjeta.
- El resultado se lee de VTEX, no del listener
Después de la transferencia, la app no debe esperar state.paymentStatus: permanece nulo en este flujo. 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 un estado del listener, o si un 2xx se trata como aprobado sin leer la orden.
- FAIL si la app puede dejar al comprador en un loader después de conocerse el resultado: con
keepLoader: trueen la configuración del SDK, debe llamarse aYuno.hideLoader()una vez decidido el resultado.
Formato del informe
Diagnósticos para capturar de una ejecución fallida en un dispositivo
Cuando las verificaciones pasan y la wallet aún 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:
paymentStatus,substatusy el mapamessagecompleto. - El modelo del dispositivo y la versión del sistema operativo, la build de la app (release/debug) y la versión de
yuno. - Si apareció la hoja nativa de la wallet y qué mostraba al cerrarse.
- El
orderGroupde VTEX, el estado HTTP y el body degatewayCallback, y el estado de la orden leído después.