Skip to main content

​
Configuration Reference

This document provides a detailed reference for all configuration options available in the Paysight Widget SDK.

​
Basic Configuration

The basic configuration requires only a few essential parameters to get started: 
const config = {
  productId: 'prod_123',
  sessionId: 'session_123',
  amount: 2999,
  currency: 'USD'
};

​
Complete Configuration

Here’s a complete reference of all available configuration options: 
interface WidgetConfig {
  // Required Configuration
  productId: string;        // Your product ID
  sessionId: string;        // Unique session identifier
  amount: number;          // Amount in smallest currency unit (e.g., cents)

  // Environment
  environment?: 'production' | 'sandbox' | 'local';  // Default: 'production'
  
  // Payment Options
  currency?: string;       // ISO 4217 currency code (e.g., 'USD', 'EUR')
  locale?: string;        // Language/locale code (e.g., 'en-US', 'fr-FR')
  threeDSRequired?: boolean; // Enable 3D Secure authentication
  failOnThreeDSChallenge?: boolean; // Do not display 3DS challenge if set to true. Proceed to payment without 3DS.
  cancelOnThreeDSFailure?: boolean; // Cancel the payment if the 3DS not successfully completed.
  ecom?: boolean;         // Enable e-commerce mode
  
  // Customer Information
  customer?: {
    email?: string;       // Customer email address
    name?: string;        // Customer full name
    phone?: string;       // Customer phone number
    address?: {
      line1?: string;     // Street address
      line2?: string;     // Additional address info
      city?: string;      // City
      state?: string;     // State/Province
      postal_code?: string; // ZIP/Postal code
      country?: string;   // Country code (ISO 3166-1)
    };
  };

  // Additional Data
  data?: {
    clickId?: string;     // Tracking click identifier
    [key: string]: any;   // Other custom data
  };

  // Appearance
  theme?: {
    font?: string;        // Custom font URL
    css?: {               // Custom CSS styles
      [selector: string]: {
        [property: string]: string | number;
      };
    };
  };

  // Field Configuration
  fields?: {
    [fieldName: string]: {
      type: FieldType;
      required?: boolean;
      position?: 'above' | 'below';
      size?: 'full' | 'half';
      label?: string;
      placeholder?: string;
      validation?: {
        pattern?: string;
        message?: string;
      };
    };
  };

  // Callbacks
  callbacks?: {
    onSuccess?: (result: PaymentResult) => void;
    onError?: (error: PaymentError) => void;
    onCancel?: () => void;
  };

  // Additional Options
  metadata?: Record<string, any>;  // Custom metadata
  debug?: boolean;                // Enable debug mode
}

​
Configuration Options

​
Required Fields

OptionTypeDescription
productIdstringYour unique product identifier
sessionIdstringUnique session identifier for the transaction
amountnumberPayment amount in smallest currency unit (e.g., cents)

​
Environment Options

OptionTypeDefaultDescription
environmentstring’production’Payment environment (‘production’, ‘sandbox’, ‘local’)

​
Payment Options

OptionTypeDefaultDescription
currencystring’USD’ISO 4217 currency code
localestring’en-US’Language/locale code
threeDSRequiredbooleanfalseEnable 3D Secure authentication
failOnThreeDSChallengebooleanfalseDo not display 3DS challenge if set to true. Proceed to payment without 3DS.
cancelOnThreeDSFailurebooleanfalseCancel the payment if the 3DS not successfully completed.
ecombooleanfalseEnable e-commerce mode

​
Customer Information

OptionTypeRequiredDescription
customer.emailstringNoCustomer email address
customer.namestringNoCustomer full name
customer.phonestringNoCustomer phone number
customer.addressobjectNoCustomer address details

​
Additional Data Options

OptionTypeRequiredDescription
data.campaignIdstringNoPaysight tracking campaign identifier
data.affiliateIdstringNoPaysight tracking affiliate identifier
data.subAffiliateIdstringNoPaysight tracking sub-affiliate identifier
data.trackhouseClickIdstringNoPaysight tracking click identifier
data.clickIdstringNoGeneric tracking click identifier for analytics and attribution
data.gclidstringNoGoogle Click Identifier for tracking ad clicks
data.wbraidstringNoWeb BRAID identifier for Google Ads tracking
data.gbraidstringNoGoogle BRAID identifier for app conversion tracking
data.[key]anyNoAny additional custom data key-value pairs

​
Theme Configuration

OptionTypeDescription
theme.fontstringCustom font URL
theme.cssobjectCustom CSS styles

​
Usage Examples

​
Basic Configuration

const config = {
  productId: 'prod_123',
  sessionId: 'session_123',
  amount: 2999,
  currency: 'USD'
};

const widget = PaysightSDK.createWidget({
  targetId: 'widget-container',
  config
});

​
Advanced Configuration

const config = {
  // Required fields
  productId: 'prod_123',
  sessionId: 'session_123',
  amount: 2999,
  
  // Environment
  environment: 'production',
  
  // Payment options
  currency: 'USD',
  locale: 'en-US',
  threeDSRequired: true,
  failOnThreeDSChallenge: false,
  cancelOnThreeDSFailure: false,
  ecom: true,
  
  // Customer information
  customer: {
    email: 'customer@example.com',
    name: 'John Doe',
    phone: '+1234567890',
    address: {
      line1: '123 Main St',
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94105',
      country: 'US'
    }
  },

  // Additional data
  data: {
    clickId: 'clk_123xyz', // Tracking click ID
    source: 'facebook',    // Example of other custom data
    campaign: 'summer_sale'
  },
  
  // Theme customization
  theme: {
    font: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap',
    css: {
      input: {
        borderRadius: '8px',
        fontSize: '15px'
      },
      button: {
        backgroundColor: '#6366f1',
        color: '#ffffff'
      }
    }
  },
  
  // Field configuration
  fields: {
    card: {
      type: 'card',
      required: true,
      position: 'above',
      size: 'full',
      label: 'Card Number',
      placeholder: '1234 5678 9012 3456'
    },
    cvv: {
      type: 'cvv',
      required: true,
      position: 'below',
      size: 'half',
      label: 'Security Code'
    }
  },
  
  // Additional options
  metadata: {
    orderId: 'order_123',
    customerId: 'cust_123'
  },
  debug: true
};

​
Environment-Specific Configuration

const config = {
  productId: 'prod_123',
  sessionId: 'session_123',
  amount: 2999,
  
  // Development environment
  environment: 'sandbox',
  debug: true,
  
  // Test card data
  customer: {
    email: 'test@example.com',
    name: 'Test User'
  }
};

​
3D Secure Configuration

const config = {
  productId: 'prod_123',
  sessionId: 'session_123',
  amount: 2999,
  
  // Enable 3D Secure
  threeDSRequired: true,
  failOnThreeDSChallenge: false,
  cancelOnThreeDSFailure: false,
  
  // Additional 3DS options
  callbacks: {
    onSuccess: (result) => {
      console.log('3DS verification successful:', result);
    },
    onError: (error) => {
      console.error('3DS verification failed:', error);
    }
  }
};

​
Best Practices

  1. Session ID Generation
const generateSessionId = () => {
  return \`session_\${Date.now()}_\${Math.random().toString(36).slice(2)}\`;
};

const config = {
  sessionId: generateSessionId(),
  // ... other options
};
  1. Environment Management
const config = {
  environment: process.env.NODE_ENV === 'production' ? 'production' : 'sandbox',
  debug: process.env.NODE_ENV !== 'production',
  // ... other options
};
  1. Field Validation
const config = {
  fields: {
    email: {
      type: 'email',
      required: true,
      validation: {
        pattern: '^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$',
        message: 'Please enter a valid email address'
      }
    }
  }
};

​
Next Steps