> ## 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.

# Set up Yuno on VTEX

> Start accepting payments with Yuno on your VTEX store by following this end-to-end configuration guide.

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** (to register Yuno as a payment provider, install the Payment App, and activate payment methods) and your **Yuno dashboard** (to 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**.

***

<Steps>
  <Step title="Configure Yuno as a payment provider">
    1. In the **VTEX dashboard**, open the left-hand menu and go to **Store Settings → Payment → Providers**, then click **New Provider** at the top right.

    <Frame>
      <img src="https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/image-065c1400.png?fit=max&auto=format&n=z8Jixp_IwgkBlbdW&q=85&s=8337a6566dd698dc04a51133a16a4429" alt="New Provider in VTEX" width="1100" height="393" data-path="images/plugins/vtex/image-065c1400.png" />
    </Frame>

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

    <Frame>
      <img src="https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/image-d4b7cb65.png?fit=max&auto=format&n=z8Jixp_IwgkBlbdW&q=85&s=dbec2bacc93f98073c25116c82e6cb26" alt="Search for Yuno provider" width="1100" height="430" data-path="images/plugins/vtex/image-d4b7cb65.png" />
    </Frame>

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

    <Accordion title="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](https://help.vtex.com/docs/tutorials/api-keys#generating-internal-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.  |
    </Accordion>

    <Accordion title="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**: Same as default.                                                                       |
      | **Automatic capture immediately after anti-fraud analysis**   | **Immediate Capture**: Behaves the same as immediate capture.                                                 |
      | **Disabled**                                                  | **Authorize Only**: The transaction is only authorized. Capture happens later when the order is **invoiced**. |
    </Accordion>

    <Note>
      **Environments**: The Yuno environment is determined by the prefix of your **Public API Key**: `dev_`, `staging_`, `sandbox_`, or `prod_`.
    </Note>

    <Tip>
      We suggest using **Use behavior recommended by payment processor** unless your business specifically requires capture after invoicing.
    </Tip>
  </Step>

  <Step title="Install the Yuno Payment App">
    After saving the provider configuration, install the Yuno Payment App from your VTEX dashboard.

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

    <Frame>
      <img src="https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/image-c64bef9b.png?fit=max&auto=format&n=z8Jixp_IwgkBlbdW&q=85&s=cb08f018fbbabe5978937d6ae2f3ec85" alt="Install Yuno Payment App" width="1914" height="854" data-path="images/plugins/vtex/image-c64bef9b.png" />
    </Frame>

    3. Click **Install** to complete the setup.

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

  <Step title="Activate payment methods">
    Now choose which payment methods you want to offer to your shoppers and route them through Yuno.

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

    <Frame>
      <img src="https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/image-68c9e7f2.png?fit=max&auto=format&n=z8Jixp_IwgkBlbdW&q=85&s=113ff69653f5e2bc3516f474e8c950b2" alt="Add Payment Condition" width="2500" height="1110" data-path="images/plugins/vtex/image-68c9e7f2.png" />
    </Frame>

    2. Select the payment method you want to activate (for example, Visa, Mastercard, Pix, Apple Pay, or any of the **Yuno \*** generic methods).

    <Frame>
      <img src="https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/image-309cec4b.png?fit=max&auto=format&n=z8Jixp_IwgkBlbdW&q=85&s=1b231665433a72bc349afc1520d54446" alt="Select Payment Method" width="2500" height="1137" data-path="images/plugins/vtex/image-309cec4b.png" />
    </Frame>

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

    <Frame>
      <img src="https://mintcdn.com/yuno-3979e326/z8Jixp_IwgkBlbdW/images/plugins/vtex/image-73d8fe62.png?fit=max&auto=format&n=z8Jixp_IwgkBlbdW&q=85&s=68cb827a7c70b3c8b9b8e6b360a9e89d" alt="Configure Payment Affiliation" width="2500" height="938" data-path="images/plugins/vtex/image-73d8fe62.png" />
    </Frame>

    <Note>
      Repeat for every method you want to offer. You can review the full list of available methods in the [Overview](/docs/plugins/vtex) page.
    </Note>
  </Step>

  <Step title="Configure the webhook in your Yuno dashboard">
    The webhook keeps your VTEX orders in sync with Yuno's payment status updates.

    1. In the **Yuno dashboard**, open **Developers → Webhooks** and click **Add webhook**.
    2. 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 (e.g., `VTEX`).
    3. Select all events and click **Add**.
  </Step>
</Steps>

***

## Advanced Scenarios

### Multi-affiliation

A single VTEX account can be connected to **more than one Yuno integration** when you need to process different payment methods through different Yuno accounts. For example, you can assign one Yuno account to credit cards and a different one to wallets.

To set this up, repeat Step 1 once per integration, giving each one a distinct **Affiliation Name**. Then, when activating payment methods, use the **Process with affiliation** field to choose which account should process it.

### Multi-account

If your business runs **multiple VTEX accounts** (e.g., a franchise model sharing the same Yuno credentials), use the **Main Account** fields in the provider configuration:

* **Main Account Name**: The name of the main VTEX account.
* **Main Account App key** and **Main Account App token**: Application credentials of that main account.

When these fields are set, the plugin reads catalog and order data from the main account instead of the current one.

### Split orders (multiple sellers)

When a shopper's cart contains products from **different sellers or franchises**, VTEX splits the purchase into multiple suborders and authorizes each one independently. The Yuno integration detects this and processes **every** suborder — so the entire order is paid, not just the first part — while sharing a single antifraud session across all of them.

This works automatically; no extra setup is required. If you want to control which antifraud providers receive the shared session, use the **Antifraud Providers for Split Orders** field in the provider configuration (see the field reference in Step 1). Valid values are `RISKIFIED`, `CYBERSOURCE`, `SIGNIFYD`, and `CIELO_CYBERSOURCE_FRAUD`; when left empty, it defaults to `RISKIFIED` + `CYBERSOURCE`.