Skip to main content

​
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 (for example, 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. A single antifraud session is shared 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.

​
Antifraud session (device fingerprints)

Antifraud providers (Riskified, Signifyd, CyberSource, Cielo CyberSource) score a payment by matching the device data collected in the shopper’s browser with the session id Yuno sends in the payment. For that match to work, the browser and the server must use the same session id. The Yuno Payment App handles this for you: on the checkout page it reads the VTEX cart id (window.vtexjs.checkout.orderFormId) and reports it as the antifraud session id for RISKIFIED, SIGNIFYD, CYBERSOURCE, and CIELO_CYBERSOURCE_FRAUD. The Yuno Payment Connector sends the same orderFormId on the server side, so the session is consistent across the browser, every suborder of a split order, and the payment itself. No configuration is needed; if the cart id is not available, each provider falls back to its own generated session id and the payment is not blocked.
Cielo CyberSource requires the antifraud session id to start with your Cielo merchant ID (MID) prefix. Until this prefix is configurable in the Yuno dashboard, set it in your VTEX checkout custom JavaScript before the checkout loads:
The Payment App prepends it only to the CIELO_CYBERSOURCE_FRAUD session id (YOUR_MID_PREFIX_<orderFormId>); the other providers are not affected. When the variable is not defined, no prefix is applied.
This global variable is an interim mechanism. Once the fingerprint prefix can be configured in the Yuno dashboard, it will no longer be needed.
If you integrate the SDK directly instead of using the Payment App, pass the session ids yourself through the deviceFingerprints mount option. See Direct SDK integration.

​
Order modifications (changed order totals)

VTEX lets you change an order after checkout, when the final total turns out to be different from the amount that was authorized. This applies, for example, if you sell products by weight, where the exact total is only known once the order is picked and packed.
  • If the final total is the same or lower, VTEX captures only the final amount. No extra setup is required.
  • If the final total is higher, VTEX charges the difference as a separate, automatic charge. Since the shopper is no longer present and does not re-enter their card, Yuno charges the difference against the card they already used on the original order.
To enable automatic charges when an order total increases, configure the following in your provider settings before the orders you expect to modify are placed:
Order-total increases are supported for credit cards only (a VTEX restriction). The card is stored at the time of the original payment, so Vault Card for Order Modification and Create Customer must be enabled before the order is placed. Turning them on later does not apply to orders that already exist.
Franchises / multiple accounts: enable Vault Card for Order Modification and Create Customer on every affiliation you use (each franchise or sub-account), and set the Main Account fields as described under Multi-account.

​
Network tokens (repeat card purchases)

Network tokens replace the card number with a token issued by the card network (Visa, Mastercard, American Express). Paying with a network token instead of the card number improves approval rates for returning shoppers and keeps working when the card is reissued, because the network updates the token automatically. Yuno can only attach a network token to a card it has securely stored. When Enable Network Tokens is on, the plugin stores each card the first time a customer pays with it and reuses that stored reference on every later purchase of the same card by the same customer. No storefront or Payment App change is needed; everything happens on the Yuno side of the integration.

​
What has to be switched on

Both sides are required. Until Yuno activates network tokens on your routes, the plugin stores cards but every payment is still processed with the card number and no network token is issued. The reverse also holds: if network tokens are active on your routes but Enable Network Tokens and Create Customer are not set in VTEX, no card is stored and every payment remains a regular card-number transaction. Confirm the activation with your KAM or support before expecting any change in approval rates.

​
Enable it

In your provider configuration (Step 1), set the following two fields and save:
Create Customer and Enable Network Tokens set to Yes in the Yuno provider configuration

​
What to expect

  • First purchase with a card: processed with the card number, as today. The card is stored at the end of that purchase.
  • Later purchases of the same card by the same customer: processed with the network token.
  • Gradual ramp-up: because every card’s first purchase still uses the card number, you will see almost no network tokens on day one. The benefit builds up as customers return with a card they have already used on your store.
  • Reissued cards (for example, a new expiration date after a renewal) keep being recognized, so the network token continues to be used.
  • Fallback: if the stored reference is not available for any reason, the payment proceeds with the card number exactly as it does today. Enabling this feature never causes a payment to fail.
  • VTEX subscriptions are not affected. Recurring charges have their own stored-credential flow, which keeps working as described in the FAQs.
  • Applies to all card payments processed through the plugin, including fraud-defense payments and split orders.
Order modifications are not affected. Storing a card for network tokens does not by itself allow the plugin to charge it again. Additional charges when an order total increases remain controlled only by Vault Card for Order Modification: with that field set to No, an order-total increase is declined even though the card is stored.
Store B has no record of the card, so it is treated as a first purchase. The payment still succeeds; it falls back to the card number.

​
Multiple accounts and franchises

The card is stored in the VTEX account that authorizes the payment and is scoped to that account’s Yuno Account ID. Keep this in mind in the following setups:
  • Authorization and payment in different VTEX accounts (for example, a B2B storefront that completes the payment in a second account): enable both fields on the affiliation of the account that authorizes the order, not only on the account that completes the payment. Both accounts must run plugin version 4.2.347 or later.
  • Franchises / multiple store accounts (many store accounts sharing a main account): enable both fields on every franchise affiliation. A card stored by one store account is not shared with another, and a card stored under one Yuno Account ID is not visible to another, so each store builds its own card history. The benefit therefore accrues per store: a chain whose customers buy across several stores gets materially fewer tokenized payments than a single-store merchant, because each store only recognizes the cards first used in that same store. Route activation is also per Yuno Account ID, so Yuno must activate network tokens on the routes of every franchise account, not only the main one.
Place two orders with the same card and the same customer on the store, then look up the plugin logs for each order in Datadog and filter by the step_function attribute:A repeat purchase that shows cardVaultLookup without a match usually means the two orders did not share the same Yuno customer (check Create Customer), were placed from different store accounts, or used a different card. If the stored reference is passed but the payment still shows a card number on the Yuno side, network tokens are not yet enabled on the route.

​
Corporate purchases (Brazil)

In Brazil, purchases made on behalf of a company must be paid and invoiced against the company’s CNPJ, not the personal CPF of the person placing the order. When a shopper checks out as a company (pessoa jurídica), VTEX sends both identities to the plugin: the shopper’s name and CPF, and the company’s legal name (razão social), trade name (nome fantasia) and CNPJ. By default the plugin uses the shopper’s personal identity. With Use Corporate Buyer Data set to Yes, corporate orders are paid under the company instead: the boleto is issued to the CNPJ, and every other payment method (cards, PIX, wallets) carries the company as the payer in Yuno.

​
Enable it

In your provider configuration (Step 1), set Use Corporate Buyer Data to Yes and save. No storefront or Payment App change is needed.

​
What to expect

  • Same shopper, different roles. A shopper can place one order as a company and the next as an individual; each order carries the identity used at checkout, regardless of what earlier orders sent.
  • Fail-safe. If the company data is incomplete (for example no CNPJ), the order falls back to the shopper’s personal identity and the payment proceeds.
  • Wallets created before the order. Apple Pay, Google Pay and Click to Pay payments that are created during page load, before the order exists, keep the identity collected by the storefront.
Franchises / multiple accounts: enable the field on every affiliation whose orders should use the company identity, and in setups where one account authorizes and another completes the payment, on the affiliation of the account that authorizes.
Place a corporate order on the store and open the created payment in the Yuno dashboard, or look up the plugin logs in Datadog (step_name:"After get payment") and check the payment request:If the request still carries the CPF, confirm that Use Corporate Buyer Data appears in the affiliation’s saved settings (the affiliation must be saved again after the plugin is upgraded to 4.2.350) and that the order’s billing address is in Brazil.