VTEX Headless Integration

Overview

This guide covers integrating Yuno with VTEX Headless for merchants using custom frontends instead of VTEX IO’s standard checkout. The VTEX Headless flow lets you control the UI while the Yuno VTEX connector handles payment processing.

For standard VTEX IO integration, see the VTEX Plugin page.

VTEX IO Applications

Two VTEX IO applications are required:

Application	Purpose
`yunopartnerbr.yuno`	PPF connector facilitating integration between VTEX and Yuno’s payment infrastructure
`yunopartnerbr.yuno-app`	Frontend payment app for Card or Click to Pay payments (not required for PIX, Boleto, or redirect-based methods)

The payment app:

Runs Yuno Web SDK to collect browser data
Executes third-party fraud detection SDKs
Processes payments directly within Yuno
Supports two credit card payments

Installation

Install the Connector (`yunopartnerbr.yuno`)

Log into your VTEX store account.
Navigate to Store Settings > Providers in VTEX Admin.
Click New Provider.
Search for and select Yuno.
Click Install and follow setup instructions.

Install the Payment App (`yunopartnerbr.yuno-app`)

Required for card-based payments:

Go to Apps > App Management in VTEX Admin.
Search for Yuno.
Select Yuno Payment App (second option).
Click Install.

Install SDK Web VTEX (npm)

For headless projects, install the SDK via npm:

npm install @yuno-payments/sdk-web-vtex

import { loadScript } from '@yuno-payments/sdk-web-vtex'

const yunoVTEX = await loadScript()
yunoVTEX.mount({ /* ... */ })

Headless Payment Flow

The headless flow works as follows:

User clicks pay button in your custom frontend.
VTEX backend sends payment information to the Yuno connector.
Connector sends credit card information to Yuno API.
API returns a one-time token.
Connector informs VTEX to open payment app with token.
Your frontend opens Yuno SDK Web VTEX with provided data.
Payment details, browser information, and fraud data are sent to the connector.
Connector processes payment via {{merchant's domain}}/_v/yunopartnerbr.yuno/v4/payments/yuno.
User receives payment status confirmation.

SDK Web VTEX Configuration

Include the script in your HTML:

<!DOCTYPE html>
<html>
<head>
  <script src="https://sdk-web-vtex.y.uno/v1/main.js"></script>
</head>
<body>
  <div id="root-container"></div>
  <script>
    window.YunoVTEX.mount({
      elementRoot: "root-container",
      payload: '{}',
      language: 'pt',
      domainVTEX: 'https://myvtex.yunopartnerbr.com',
      onPaymentDone: (paymentData) => {
        console.log(paymentData);
      },
      onError: (message, error) => {
        console.log(message, error);
      },
      onLoading: (loading) => {
        console.log(loading);
      }
    });
  </script>
</body>
</html>

SDK Parameters

Property	Type	Required	Description
`elementRoot`	String	Yes	HTML element ID to mount the SDK
`payload`	String	Yes	Connector response data (JSON string)
`language`	String	Yes	ISO 639-1 language code (e.g., `"pt"`)
`domainVTEX`	String	No	Your VTEX domain
`onPaymentDone`	Function	No	Called when payment completes
`onError`	Function	No	Called on errors
`onLoading`	Function	No	Called during payment processing

Payload Structure

The payload parameter receives a JSON string from the connector response:

{
  "isVTEXCard": true,
  "checkoutSessions": ["session-id"],
  "paymentIds": ["payment-id"],
  "orderId": "order-id"
}

PIX Flow (Headless)

For PIX and other alternative payment methods, the flow differs:

User clicks pay button.
VTEX backend sends payment information to the connector.
Connector creates payment in Yuno.
Yuno generates QR code and payment details, returns to VTEX.
Your frontend displays the PIX QR code or redirects the user to complete payment.

Seller ID / Affiliate Code

The VTEX connector captures sellerId (Affiliate Code) from VTEX orders and includes it in checkout session and payment metadata:

{
  "metadata": [
    {
      "key": "sellerId",
      "value": "affiliate_code_from_vtex_order"
    }
  ]
}

This supports VTEX’s Affiliate mode for marketplace participation and attribution tracking.

The connector automatically generates and formats payloads. You don’t need to modify them manually. Payload structure adapts based on the selected payment method.

Getting Started

Core Concepts

Platform

Guides

Features

Security

AI

Troubleshooting

Reference

Overview

VTEX IO Applications

Installation

Install the Connector (`yunopartnerbr.yuno`)

Install the Payment App (`yunopartnerbr.yuno-app`)

Install SDK Web VTEX (npm)

Headless Payment Flow

SDK Web VTEX Configuration

SDK Parameters

Payload Structure

PIX Flow (Headless)

Seller ID / Affiliate Code

​Overview

​VTEX IO Applications

​Installation

​Install the Connector (yunopartnerbr.yuno)

​Install the Payment App (yunopartnerbr.yuno-app)

​Install SDK Web VTEX (npm)

​Headless Payment Flow

​SDK Web VTEX Configuration

​SDK Parameters

​Payload Structure

​PIX Flow (Headless)

​Seller ID / Affiliate Code

Overview

VTEX IO Applications

Installation

Install the Connector (`yunopartnerbr.yuno`)

Install the Payment App (`yunopartnerbr.yuno-app`)

Install SDK Web VTEX (npm)

Headless Payment Flow

SDK Web VTEX Configuration

SDK Parameters

Payload Structure

PIX Flow (Headless)

Seller ID / Affiliate Code