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'
    }
  ]
}

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[]
}

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'