Validator: VTEX headless wallets (React Native)

Validate my Yuno VTEX headless wallet integration following CLAUDE.md.

​

The flow being validated

VTEX cart (Steps 1–5, total final)
  → POST /session/preflight                     → { checkoutSession, publicApiKey }
  → (optional) POST /installments/apm           → plans for the wallet
  → YunoSdk.initialize({ apiKey: publicApiKey, countryCode })   → the key preflight returned, nothing else
  → YunoSdk.onOneTimeToken(...) subscribed
  → YunoSdk.startPaymentLite({ checkoutSession,
        methodSelected: { paymentMethodType: APPLE_PAY | GOOGLE_PAY | CLICK_TO_PAY, vaultedToken: null },
        showPaymentStatus: false }, countryCode)
  → OTT arrives in onOneTimeToken               ← the flow only continues here
  → POST /session/preflight/payments            → body with the token, createPaymentInAuth: true → { deferred: true }
  → VTEX Step 6 transaction → Step 7 payments → Step 8 gatewayCallback
  → the connector creates the payment in Yuno during authorization and answers VTEX
  → the gatewayCallback response + GET /api/checkout/pub/orders/order-group/{orderGroup} → outcome

​

Checks

​

1. The hand-off happens only after the OTT

• Find the YunoSdk.onOneTimeToken / onOneTimeTokenInfo subscription (or the YunoSdk.startPaymentLite caller) and follow where the token goes.
• FAIL if the preflight-payments call is reachable without a token, sends token: ''/null/undefined, or runs right after await YunoSdk.startPaymentLite(...). That promise resolves when the wallet starts, not when it finishes; it never carries the token.
• FAIL if the VTEX order (Steps 6–8) can be placed before the hand-off returns { deferred: true }, or if the token is sent to /payments/yuno (the Payment App route) instead of /session/preflight/payments.
• FAIL if the hand-off can run twice for one attempt. The SDK wires two native callbacks to the same YunoOneTimeToken event, so the event can arrive more than once with the same token, and subscribing to both onOneTimeToken and onOneTimeTokenInfo doubles it again. Guard it (a ref holding the token already handed off) so the order is placed once.
• Why: the connector accepts a token-less body and answers { deferred: true }; the failure only surfaces at authorization, as a denied order with Deferred preflight payment creation failed. An app that places the order first, sends a token-less hand-off and then posts the token to /payments/yuno can complete a payment, but only while the authorization happens to arrive before the hand-off; the day it arrives after, the connector uses the token-less body and the order is denied.

​

2. createPaymentInAuth: true

​

3. The SDK is initialized with exactly the key preflight returned

• YunoSdk.initialize({ apiKey, countryCode }) must receive the publicApiKey from that same preflight response.
• Search every initialization point, JavaScript and native: 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 .
• The first initialization of the process is the one that counts. On Android this is certain: once the SDK is initialized, YunoSdk.initialize from JavaScript returns without touching the native SDK, so a later call with the preflight key changes nothing. Treat iOS the same way.
• FAIL on: a key hardcoded in App.tsx, a key from .env / remote config / build flavor, or YunoSdkModule.initialize(this, "<key>") in MainApplication.onCreate(), unless that value is proven to be the same key preflight returns for this store and environment. The SDK’s setup guide asks for that native call, so most Android apps have it: report the key’s environment prefix (sandbox_, prod_, never the full value) next to the prefix of the key preflight returns.
• FAIL if the store uses more than one Yuno affiliation (preflight called with affiliationName) and the app expects to switch keys between orders: the second key is ignored until the app restarts.
• A stale key makes the session’s first calls fail 401 and the wallet closes with no message.

​

4. Payment method type matches what VTEX authorizes

​

5. Amount, currency and country are identical in preflight and hand-off

• The amount is a JSON number in decimal units (845.90), not cents (84590) and not a string.
• The same triple amount:currency:country goes to both calls; it is fingerprinted. A mismatch is 409.
• FAIL if the amount is read from a different source in the two calls (e.g. cart total vs order total), or if either call happens before the cart total is final.
• The countryCode given to YunoSdk.initialize and to startPaymentLite is that same country. FAIL if it is a constant while the store sells in more than one country.

​

6. The total is locked before preflight, and the flow restarts if it changes

​

7. One store host per order

​

8. showPaymentStatus is off

​

9. The listeners are subscribed before the wallet starts, and stay subscribed

• FAIL if onOneTimeToken is subscribed after startPaymentLite, inside the same handler that starts the wallet, or in a component that can unmount while the wallet sheet is open (a modal or bottom sheet, a screen that navigates away).
• FAIL if a subscription is never removed (subscription.remove() in the effect cleanup): a screen mounted twice then hands off twice.
• Android only: YunoSdk.getLastOneTimeToken() returns the token of the current attempt when the event was emitted while JavaScript was paused (it is cleared when startPaymentLite starts). Reading it when the app returns to the foreground without a token is a valid recovery. On iOS it always returns null.

useEffect(() => {
  const token = YunoSdk.onOneTimeToken((ott) => {
    console.log(`[yuno] token=${ott ? 'present' : '-'}`);
    if (ott) handOffToConnector(ott); // guarded, runs once per attempt (check 1)
  });
  const status = YunoSdk.onPaymentStatus((state) => {
    console.log(`[yuno] status=${state.status}`);
  });
  return () => {
    token.remove();
    status.remove();
  };
}, []);

​

10. Split orders are not offered with wallets

​

11. Installments (only if offered, Apple Pay / Google Pay)

• /installments/apm is called after preflight, with that session’s checkoutSession + publicApiKey, once per wallet, with country and a full locale (pt-BR).
• The chosen count travels as payment_method.detail.card.installments in the hand-off body — never with CLICK_TO_PAY, and the amount stays the order total.
• Empty list, error or timeout must all render no selector and let the wallet proceed. FAIL if the checkout is blocked by this call.

​

12. Native setup

• The app is not running in Expo Go: the SDK is a native module and needs a development build or a bare project. Report how the native projects are produced (bare, expo prebuild, EAS).
• Android:
  • the Yuno Maven repo (https://yunopayments.jfrog.io/artifactory/snapshots-libs-release) is in the project-level repositories;
  • minSdkVersion 21+, compileSdkVersion 35+, Java 17, Kotlin 1.9.24+. Report the Kotlin version: the SDK module uses Jetpack Compose with the compiler extension for Kotlin 1.9, so on Kotlin 2.x report whether the module builds;
  • YunoSdkModule.initialize(...) in MainApplication.onCreate() (its key is judged in check 3);
  • YunoSdkModule.registerYunoCallbacks(this) in MainActivity.onCreate() before super.onCreate(). It is what delivers payment status events on Android; without it a wallet sheet the shopper closed is invisible to the app. Report whether it is present.
• iOS: platform :ios, '14.0' or higher in the Podfile, the app’s .entitlements file has com.apple.developer.in-app-payments listing the merchant ID registered with Yuno for this affiliation, and the App ID has the Apple Pay capability. Report the merchant ID found so it can be compared with the Yuno side. With Expo, the entitlement comes from ios.entitlements in the app config.

​

13. Testing on real builds

​

14. SDK version

• Android: com.yuno.payments:android-sdk in node_modules/@yuno-payments/yuno-sdk-react-native/android/build.gradle
• iOS: YunoSDK in node_modules/@yuno-payments/yuno-sdk-react-native/YunoSdkReactNative.podspec (YunoSdk.podspec up to 1.3.0), and the version actually installed in ios/Podfile.lock

​

15. The native SDK reaches the token service (runtime, signed build)

1. the wallet setup call — Apple Pay: .../payments/transactions/APPLE_PAY (merchant session); Google Pay: the config/sdk calls before the sheet opens
2. .../wallet/decrypt — the wallet payload came back from the sheet and was handed to Yuno
3. the token creation call (.../token or .../one-time-token) — the OTT exists

• Only 1 → the sheet never returned a payment: entitlement / merchant ID mismatch (check 12) or the user cancelled. Not an SDK defect.
• 1 and 2, no 3 → the native SDK stopped between decrypt and token. Report the version pair (check 14).
• 1, 2 and 3, but the listener logged no token → the event was emitted with nobody subscribed (check 9). On Android, read YunoSdk.getLastOneTimeToken() to confirm the token existed.
• All three and the listener logged the token → the SDK side is fine; the problem is in the hand-off (check 1).

​

16. The outcome is read from VTEX, not from the listener

• FAIL if the success/failure screen depends on onPaymentStatus, on continuePayment, or on startPaymentSeamlessLite’s return value, or if a 2xx is treated as approved without reading the order.
• FAIL if the app shows nothing between the token and the outcome. The SDK closes its UI once the token is issued (keepLoader has no effect in SDK 1.4.0, and hideLoader() does nothing on Android), so the progress state is the app’s own, and the pay button must stay disabled until the outcome is known.

​

Report format

CHECK  1  Hand-off after OTT            FAIL  src/checkout/PaymentScreen.tsx:212 — preflight/payments is called
                                              right after startPaymentLite, no token at that point
CHECK  2  createPaymentInAuth           PASS  src/api/yunoConnector.ts:64
CHECK  3  SDK key                       FAIL  android/app/src/main/java/com/store/MainApplication.kt:41 —
                                              native key prefix sandbox_, preflight returns prod_
...
CHECK 15  Native token call             FAIL  capture 2026-09-22 13:07 UTC — merchant session only, no decrypt,
                                              no token; sheet closed with "Payment Not Completed"
SDK: @yuno-payments/yuno-sdk-react-native 1.4.0 (Android 2.21.1, iOS 2.22.0), React Native 0.76.3, new architecture on

​

Diagnostics to capture from a failing device run

1. The checkoutSession from the preflight response, and the UTC timestamp of the attempt.
2. Every listener line from check 9, in order, plus the native console lines that mention Yuno. The React Native events carry the status only; the sub-status and message exist only in the native logs.
3. The device model and OS version, the app build (release/debug), the React Native version and architecture (old / new), and the SDK versions from check 14.
4. Whether the native wallet sheet appeared, and what it showed when it closed.
5. The VTEX orderGroup, the gatewayCallback HTTP status and body, and the order status read afterwards.

​

SDK versions