SDK Web VTEX

A TypeScript SDK for integrating Yuno payments into headless VTEX stores. This package provides a simple interface to load and mount the Yuno VTEX payment solution with full type safety.

VTEX Headless Integration Guide

Installation

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

Basic Usage

import { loadScript } from '@yuno-payments/sdk-web-vtex'
import type { YunoVTEXInterface, MountProps } from '@yuno-payments/sdk-web-vtex'

// Load the SDK
const yunoVTEX: YunoVTEXInterface = await loadScript()

const payload = "{\"isVTEXCard\":true,\"checkoutSessions\":[\"bd0c0a6e\"],\"paymentIds\":[\"ABC\"],\"orderId\":\"123\"}"

// Mount the payment interface
await yunoVTEX.mount({
  elementRoot: '#payment-container',
  payload,
  language: 'en'
})

Advanced Configuration

Loading with Environment Options

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

// Load from specific environment (for testing)
const yunoVTEX = await loadScript({
  env: 'sandbox',        // 'dev' | 'staging' | 'sandbox' | 'prod'
  version: 'v2.0'        // Custom SDK version
})

Complete Mount Configuration

import type { MountProps, OnPaymentDoneParams } from '@yuno-payments/sdk-web-vtex'

const mountProps: MountProps = {
  // Required properties
  elementRoot: '#payment-container',
  payload: '{}',
  language: 'en',

  // Optional VTEX configuration
  domainVTEX: 'mystore.vtexcommercestable.com.br',
  proxyUrlVTEX: 'https://proxy.mystore.com',

  // Event handlers
  onPaymentDone: (paymentData: OnPaymentDoneParams) => {
    console.log('Payment completed:', paymentData)
    if (paymentData.success) {
      // Handle successful payment
      paymentData.payments?.forEach(payment => {
        console.log(`Order ${payment.orderId}: ${payment.status}`)
      })
    }
  },

  onError: (message: string, error?: any) => {
    console.error('Payment error:', message, error)
  },

  onLoading: (loading: boolean) => {
    console.log('Loading state:', loading)
  },

  // SDK configuration overrides
  sdkWebEnv: 'sandbox',
  sdkWebVersion: 'v2.0',

  // Device fingerprinting for fraud prevention
  deviceFingerprints: [
    {
      provider_id: 'RISKIFIED',
      session_id: 'riskified-session-123'
    }
  ],

  // Version of the payment app hosting this bundle
  appVersion: '1.9.75'
}

await yunoVTEX.mount(mountProps)

API Reference

Types and Interfaces

YunoVTEXInterface

Main interface for the Yuno VTEX SDK.

interface YunoVTEXInterface {
  mount: (props: MountProps) => Promise<void>
  unmount: () => Promise<void>
}

LoadScriptProps

Configuration options for loading the SDK.

type LoadScriptProps = {
  env?: 'dev' | 'staging' | 'sandbox' | 'prod'  // Environment (default: 'prod')
  version?: string                               // SDK version (default: latest)
}

MountProps

Configuration for mounting the payment interface.

type MountProps = {
  // Required
  elementRoot: string                    // CSS selector for container element
  payload: string                        // Checkout session token
  language: string                       // Language code (e.g., 'en', 'es', 'pt')
  
  // Optional VTEX specific
  domainVTEX?: string                   // VTEX store domain
  proxyUrlVTEX?: string                 // VTEX proxy URL
  
  // Event handlers
  onPaymentDone?: (paymentData: OnPaymentDoneParams) => void
  onError?: (message: string, error?: any) => void
  onLoading?: (loading: boolean) => void
  
  // SDK overrides
  sdkWebEnv?: 'dev' | 'staging' | 'sandbox' | 'prod'
  sdkWebVersion?: string
  
  // Fraud prevention
  deviceFingerprints?: ExternalProviderId[]

  // Plugin attribution
  appVersion?: string | null            // VTEX payment app version
}

OnPaymentDoneParams

Payment completion data structure.

type OnPaymentDoneParams = {
  payments?: {
    status: string      // Payment status
    orderId: string     // Order identifier
    paymentId: string   // Payment identifier
  }[]
  success: boolean      // Overall success flag
}

ExternalProviderId

External provider identification for device fingerprinting.

type ExternalProviderId = {
  provider_id: string   // Provider identifier (e.g., 'RISKIFIED')
  session_id: string    // Session identifier within the provider's system
}

Usage Examples

Basic Payment Flow

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

async function initializePayment() {
  try {
    // Load SDK
    const yunoVTEX = await loadScript()
    
    // Mount payment interface
    await yunoVTEX.mount({
      elementRoot: '#payment-container',
      payload: 'your-checkout-session-token',
      language: 'en',
      onPaymentDone: (data) => {
        if (data.success) {
          window.location.href = '/success'
        } else {
          console.error('Payment failed')
        }
      },
      onError: (message, error) => {
        console.error('Payment error:', message, error)
      }
    })
  } catch (error) {
    console.error('Failed to initialize payment:', error)
  }
}

Testing with Different Environments

// Development environment
const devYuno = await loadScript({ env: 'dev' })

// Staging environment  
const stagingYuno = await loadScript({ env: 'staging' })

// Sandbox environment (recommended for testing)
const sandboxYuno = await loadScript({ env: 'sandbox' })

Cleanup

// Unmount when component is destroyed or route changes
await yunoVTEX.unmount()

Environment URLs

The SDK loads from different URLs based on the environment:

• dev: https://sdk-web-vtex.dev.y.uno/[version]/main.js
• staging: https://sdk-web-vtex.staging.y.uno/[version]/main.js
• sandbox: https://sdk-web-vtex.sandbox.y.uno/[version]/main.js
• prod: https://sdk-web-vtex.y.uno/[version]/main.js (default)

TypeScript Support

This package is written in TypeScript and provides full type definitions. All interfaces and types are exported for use in your TypeScript projects.

import type { 
  YunoVTEXInterface, 
  MountProps, 
  OnPaymentDoneParams,
  ExternalProviderId,
  LoadScript 
} from '@yuno-payments/sdk-web-vtex'

Device fingerprints

deviceFingerprints lets the host page choose the session id the Yuno Web SDK reports to each antifraud provider, instead of the one the provider's own script generates. Use it when the same identifier must be known server-side (for example, the VTEX orderFormId, which the Yuno Payment Connector also sends for split orders).

type ExternalProviderId = {
  provider_id: string   // antifraud provider id as configured in the Yuno dashboard
  session_id: string    // session id to report for that provider
}

• Entries are matched by provider_id against the fraud providers configured for the merchant; unknown or unconfigured providers are ignored.
• When a match exists, the supplied session_id replaces the provider-generated one.
• When deviceFingerprints is omitted, every provider uses its own generated session id.

Provider ids used by the VTEX Payment App: RISKIFIED, SIGNIFYD, CYBERSOURCE, CIELO_CYBERSOURCE_FRAUD. The Payment App sets all of them to window.vtexjs.checkout.orderFormId, prefixing the CIELO_CYBERSOURCE_FRAUD one with window.yunoFingerprintPrefix when a merchant defines it (Cielo MID prefix requirement).

const orderFormId = window.vtexjs?.checkout?.orderFormId

await yunoVTEX.mount({
  // ...
  deviceFingerprints: orderFormId && [
    { provider_id: 'RISKIFIED', session_id: orderFormId },
    { provider_id: 'CYBERSOURCE', session_id: orderFormId },
  ],
})

Plugin attribution

appVersion reports the version of the VTEX payment app (yunopartnerbr.yuno-app) that hosts this bundle. It travels to the Yuno Web SDK and is stamped on every SDK event as app_version, alongside plugin_platform and plugin_version.

The VTEX plugin ships as more than one independently versioned component, and one field cannot carry them all:

• plugin_version — the connector (yunopartnerbr.yuno). Canonical across every event; it holds the core logic and travels in the checkout payload, so this package never has to supply it.
• app_version — the payment app, supplied through this prop.

They are reported separately because the absence alert for plugin.activated groups by app_version: attributing it to the connector would point the alert at a component that may not have changed.

import { APP_VERSION } from './lib/monitoring/app-version'

await yunoVTEX.mount({
  // ...
  appVersion: APP_VERSION,
})

Omit it on headless storefronts. Merchants running a headless architecture embed this bundle directly, without the VTEX payment app, so there is no app version to report. The prop is optional and resolves to null in that case, which is the correct value rather than a missing one — nothing downstream assumes it is populated.