> ## Documentation Index > Fetch the complete documentation index at: https://docs.y.uno/llms.txt > Use this file to discover all available pages before exploring further. # Validator: VTEX headless Web > A read-only checklist for AI coding agents that audits a VTEX headless storefront or WebView page that mounts the Yuno SDK Web for VTEX. Drop this file in the root of the repository that serves the page mounting the Yuno SDK Web for VTEX (your headless storefront, or the page your mobile app loads in a WebView) and ask Claude Code: > Validate my Yuno VTEX headless Web integration following this file. It works the same with any coding agent (Cursor, Codex, Copilot): paste the file as the prompt. It audits the code against the public guide *"Headless SDK integration"* (docs.y.uno/docs/plugins/vtex/direct-sdk-integration) and reports what is wrong, with file and line. It only reads code and changes nothing unless you ask. ## The flow being validated ``` VTEX headless checkout: orderForm -> POST .../transaction -> POST /api/payments/transactions/{id}/payments -> VTEX calls the Yuno connector (authorize) -> connector answers paymentAppData.payload -> POST /api/checkout/pub/gatewayCallback/{orderGroup} <- HTTP 428, body paymentAuthorizationAppCollection[].appPayload (a JSON string: the payload) (VTEX behaviour seen in support cases, not in the guide or in Yuno code) -> await loadScript() -> injects https://sdk-web-vtex.y.uno/v1/main.js (script #yuno-vtex-script, event yuno-sdk-vtex-ready) -> await yunoVTEX.mount({ elementRoot, payload, language, domainVTEX, callbacks }) the bundle loads sdk-web v1.6 (script #yuno-script), renders the form / wallet button / fraud step -> POST {domainVTEX}{storeBasePath}/api/io/_v/yunopartnerbr.yuno/v4/payments/yuno (the bundle, never you) -> onPaymentDone({ success, payments[] }) or onError(message, error) <- your code continues only here -> Yuno webhook -> connector -> VTEX re-polls authorize -> order approved / denied ``` The bundle never talks to the VTEX transaction API. Your page owns everything after `onPaymentDone`. Statements marked "support cases" or "public guide" are context: they explain a symptom but are never a FAIL condition on their own. Every FAIL below is something you can see in the code. ## Checks Report each one as PASS / FAIL / N/A with the evidence (file:line). Do not pass a check because the code "looks right": quote the line that proves it. Start by finding every use of the SDK: `grep -rn "sdk-web-vtex\|YunoVTEX\|loadScript\|\.mount(\|unmount(\|domainVTEX\|proxyUrlVTEX" --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build .` ### 1. Mount runs only after the connector payload exists * Trace where `payload` comes from. Per the public guide it is the payload the Yuno connector returns during the authorization step of this order, and it must exist before `mount`. Support cases show VTEX delivering it as the `appPayload` of a 428 answer to `gatewayCallback` (or your backend relaying `paymentAppData.payload`). * FAIL if `mount` can run before the code has received that payload (page load, `useEffect` with no payload guard, a timer), with a hardcoded or sample payload (the README/guide sample `"{\"isVTEXCard\":true,...}"`), or with a payload cached from a previous order. * Why: the bundle has no payment context of its own. An empty payload throws `payload = ... is not valid`; a stale one renders a checkout session that belongs to another order. ### 2. The payload is passed as the unparsed string * `MountProps.payload` is typed `string`; the bundle calls `JSON.parse(payload)` itself. * FAIL if the code passes an object, or re-serializes a modified copy. Passing an object throws `value.trim is not a function` from the mount validation, before `onError` can run. ### 3. `elementRoot` is an element id that exists and stays * `elementRoot` is passed to `document.getElementById`, so it is a bare id: `'yuno-sdk-root'`, not `'#yuno-sdk-root'` (the npm README shows `'#payment-container'`, which does not work). * The element must be in the DOM when `mount` is awaited and must not be replaced while the shopper pays (React `key` change, conditional render, SPA route swap). * FAIL on a `#` or `.` prefix, a mount before the element renders, or a container that re-renders mid-payment. * Why: a missing element calls `onError('Element with id not found')` and throws; a replaced element leaves the checkout detached and the shopper on a blank area. ### 4. One mount per order, and `unmount` on teardown * `window.YunoVTEX` is a single instance with one React root. A second `mount` silently unmounts the first, whatever element it targets. Check that `mount` is called once per order: not in a render body, not in an effect without a run-once guard, not in a `window.addEventListener('message', ...)` handler that accepts any message (the Yuno WebView demo does this; filter by a `type` of your own bridge contract and ignore the rest). * `await yunoVTEX.unmount()` must run when the page or component is torn down (route change, component destroy, WebView closed). The Payment App does it in the effect cleanup. * FAIL if mount can run twice for one order, or nothing calls `unmount`. `unmount` only drops the React root: `window.YunoVTEX`, `window.Yuno` and both script tags stay, which is expected. ### 5. `domainVTEX` is the exact store origin: scheme and host, no trailing slash, no path * Quote the value (and where it comes from: env var, config, string). It must look like `https://.myvtex.com` or the store's own `https://` host, lower case is fine (the code also accepts `http://`, which a production store should not use). * FAIL on: a trailing slash (`https://mystore.myvtex.com/`), any path (`https://store.com/br`), a missing scheme (`store.myvtex.com`), or a value built by concatenation that can end in `/`. * Why: the bundle lowercases the value and prepends it as is (`yuno-api.ts`), so a trailing slash produces `https:////api/io/_v/yunopartnerbr.yuno/v4/payments/yuno`. In a reported incident (a WhatsApp checkout flow), VTEX answered the CORS preflight on that URL with 405 and no CORS headers, the browser blocked the call (`Network Error`, no status), no payment was created and the orders were cancelled after 24 h. At the time of writing the production bundle does not strip the slash. A value without `http(s)://` raises `onError('Domain must be https. It is ')`. * Stores served under a sub-path use the connector's `Store Base Path` affiliation field, never a path in `domainVTEX`. If the page is served from the store origin itself, `domainVTEX` may be omitted. ### 6. `proxyUrlVTEX`, only if used, reaches the create-payment route * When set, the bundle POSTs the create payment to this value verbatim: no `domainVTEX`, no store base path and no `/api/io/...` suffix are added (`yuno-api.ts`). The value is not validated. * Two forms are seen. A bare host, as in the public guide's own example (`https://proxy.mystore.com`): the POST goes to the proxy's root, so the proxy must forward its root to `/api/io/_v/yunopartnerbr.yuno/v4/payments/yuno` of the store account. A full path: the POST goes to that path, which the proxy must forward the same way. Both work when the proxy routes them; report which form is used. * FAIL only if the proxy configuration is in this repository and shows that the value does not reach the create-payment route. Otherwise report "needs confirmation" with the value. * Note in the report: `proxyUrlVTEX` is not applied to wallet installments (`/installments/apm` uses `domainVTEX` only), so a store that reaches VTEX only through a proxy gets no wallet installment selector. ### 7. One VTEX account host per order, and no direct connector calls * The host used for the checkout calls (`orderForm`, `transaction`, `gatewayCallback`) and the host in `domainVTEX` must be the same VTEX account, and that account must have the Yuno connector affiliation configured. The affiliation itself cannot be checked in code. FAIL only if the two hosts visibly name different accounts; report "needs confirmation" if they come from separate config keys that can diverge. * FAIL if your code calls `/payments/yuno`, `/payments/yuno/status` or builds any `_v/yunopartnerbr.yuno` URL itself. The bundle creates the payment with the one-time token; a second call creates a second payment or fails. * The Payment App installation check does not apply to headless. ### 8. Only one Yuno SDK on the page * `grep -rn "sdk-web\.y\.uno\|sdk-web\.sandbox\.y\.uno\|@yuno-payments/sdk-web['\"]\|window\.Yuno\b\|yuno-script\|webpackChunksdk_web\|sdk-web-vtex\.y\.uno"` over source, HTML templates and tag-manager snippets, and ask about third-party scripts (VTEX IO express buttons, wallet snippets). * FAIL if the page also loads sdk-web directly, or adds the `sdk-web-vtex` bundle with its own `