Set up Yuno on VTEX

This page walks you through every step needed to start accepting payments with Yuno on your VTEX store. The setup happens in two places. Your VTEX dashboard is where you register Yuno as a payment provider, install the Payment App, and activate payment methods. Your Yuno dashboard is where you configure the webhook that keeps order status in sync.

Before you start

Have the following ready:

A user with administrator access to your VTEX dashboard.
Your Yuno credentials, which you can find in your Yuno dashboard under Developers → API Credentials: Account ID, Public API Key, and Private Secret Key.

Configure Yuno as a payment provider

In the VTEX dashboard, open the left-hand menu and go to Store Settings → Payment → Providers, then click New Provider at the top right.

In the Select a provider dialog, type Yuno in the search box and select Yuno from the results.

Fill in the provider configuration form and save. Once saved, the provider is registered, but no payment methods are active yet.

Field reference

Field	Required	What it does
Application Key / Application Token	Yes	VTEX admin credentials the plugin uses to interact with VTEX on your behalf. See VTEX’s guide on generating Application Keys.
Automatic Settlement	Yes	Defines when the payment is captured automatically after authorization. Applies to card and wallet payments only.
Affiliation Name	Yes	A human-readable name for this Yuno integration.
Account ID	Yes	Your Yuno Account ID, available in your Yuno dashboard.
Public API Key	Yes	Your Yuno Public API Key. The prefix determines the environment.
Private Secret Key	Yes	Your Yuno Private Secret Key.
Main Account Name	Optional	For multi-account setups.
Main Account App key	Optional	Application Key of the main VTEX account.
Main Account App token	Optional	Application Token of the main VTEX account.
Soft Descriptor	Optional	Custom text that appears on the shopper’s card statement.
Create Customer	Optional	When set to Yes, the plugin creates a corresponding customer record in Yuno.
VTEX IO orderPlaced page URL	Optional	A custom URL where shoppers should be redirected after payment.
Payment Mode	Optional	Payment App (modern) or Legacy (redirect).
Transaction Identification From	Optional	Yuno TID or Provider TID.
Antifraud Providers for Split Orders	Optional	Comma-separated antifraud providers (`RISKIFIED`, `CYBERSOURCE`, `SIGNIFYD`, `CIELO_CYBERSOURCE_FRAUD`) that receive the shared session for split orders. Defaults to `RISKIFIED` + `CYBERSOURCE` when left empty.
Vault Card for Order Modification	Optional	When set to Yes (and Create Customer is also Yes), the plugin securely stores the card used on each order and allows the additional amount to be charged automatically if the order total later increases. This is the only field that authorizes additional charges: when it is No, an order-total increase is declined even if the card was stored for network tokens. See Order modifications.
Enable Network Tokens	Optional	When set to Yes (and Create Customer is also Yes), the plugin securely stores each card on its first purchase and recognizes it on later purchases by the same customer, so Yuno can process repeat purchases with a network token instead of the card number. The toggle has no effect until Yuno activates network tokens on the routes your store uses: until then cards are stored but no tokens are issued. Contact your Yuno KAM or support to activate it. See Network tokens.
Use Corporate Buyer Data	Optional	Brazil only. When set to Yes, orders placed by a shopper checking out as a company (pessoa jurídica) are paid under the company’s legal name and CNPJ instead of the shopper’s personal name and CPF, on every payment method. Default No. See Corporate purchases.

Settlement Options

The Automatic Settlement field determines the timing of the capture for card and wallet payments.

Option	Practical Behavior
Use behavior recommended by payment processor	Immediate Capture: The transaction is captured immediately after authorization. (Default)
Automatic capture immediately after payment authorization	Immediate Capture: The transaction is captured immediately after authorization. Same as default.
Automatic capture immediately after anti-fraud analysis	Immediate Capture: The transaction is captured immediately after authorization.
Disabled	Authorize Only: The transaction is only authorized. Capture happens later when the order is invoiced.

Environments: The Yuno environment is determined by the prefix of your Public API Key: dev_, staging_, sandbox_, or prod_.

We suggest using Use behavior recommended by payment processor unless your business specifically requires capture after invoicing.

Install the Yuno Payment App

After saving the provider configuration, install the Yuno Payment App from your VTEX dashboard.

In the VTEX dashboard, go to Apps → App Management.
Search for Yuno and select the Yuno Payment App in the list of available apps and open its Settings.

Click Install to complete the setup.

Once installed, the Payment App takes care of rendering the Yuno checkout experience inside your VTEX checkout.

Activate payment methods

Now choose which payment methods you want to offer to your shoppers and route them through Yuno.

In the VTEX dashboard, go to Store Settings → Payment → Settings → Payment Conditions. Click the + button to add a payment condition.

Select the payment method you want to activate (for example, Visa, Mastercard, Pix, Apple Pay, Samsung Pay, or any of the generic Yuno methods, such as Yuno Card or Yuno Wallet).

In the Process with provider field, select the Yuno affiliation you configured in Step 1. Set the Status to Active and save.

Repeat for every method you want to offer. You can review the full list of available methods in the Overview page.

Configure the webhook in your Yuno dashboard

The webhook keeps your VTEX orders in sync with Yuno’s payment status updates.

In the Yuno dashboard, open Developers → Webhooks and click Add webhook.
Fill in the form:
- Name: For example VTEX webhook.
- Endpoint URL: https://{store_name}.myvtex.com/_v/yunopartnerbr.yuno/v4/webhook, replacing {store_name} with your VTEX account name.
- x-api-key and x-secret: Enter any placeholder value (for example, VTEX).
Select all events and click Add.

Advanced Scenarios

The scenarios that go beyond the basic setup — multi-affiliation, multi-account, split orders, antifraud sessions, order modifications, network tokens, and corporate purchases — are covered on their own page.

Advanced Features

Multi-affiliation, multi-account, split orders, antifraud sessions, order modifications, network tokens, and corporate purchases.

Getting Started

Core Concepts

Using Yuno

Direct Integration Use Cases

Payment Features

Payouts and Disputes

Webhooks

Wallets

AI Capabilities

Security and Compliance

Plugins

Additional Services

Before you start

Advanced Scenarios

Advanced Features

​Before you start

​Advanced Scenarios

Advanced Features

Before you start

Advanced Scenarios