Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.paysight.io/llms.txt

Use this file to discover all available pages before exploring further.

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. Supported: 'USD', 'EUR', 'GBP', 'JPY', 'AUD', 'CAD', 'CHF', 'CNY', 'HKD', 'NZD', 'SEK', 'KRW', 'SGD', 'NOK', 'MXN', 'INR', 'RUB', 'ZAR', 'TRY', 'BRL', 'TWD', 'DKK', 'PLN', 'THB', 'IDR', 'HUF', 'CZK', 'ILS', 'CLP', 'PHP', 'AED', 'COP', 'SAR', 'MYR', 'RON'
  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?: {
    campaignId?: number;      // Paysight campaign ID
    campaignName?: string;    // Campaign name/alias; auto-assigns or creates campaign when campaignId is 0
    affiliateId?: number;     // Paysight affiliate/traffic source ID
    affiliateName?: string;   // Affiliate name/alias; auto-assigns or creates affiliate when affiliateId is 0
    subAffiliateId?: string;   // Paysight sub-affiliate ID
    trackhouseClickId?: string; // Paysight tracking click identifier
    clickId?: string;         // Generic tracking click identifier
    gclid?: string;           // Google Click Identifier
    wbraid?: string;          // Web BRAID identifier for Google Ads
    gbraid?: string;          // Google BRAID identifier for app conversions
    utm_campaign?: string;    // UTM campaign parameter
    utm_source?: string;      // UTM source parameter
    utm_medium?: string;      // UTM medium parameter
    [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;
  };

  // Payment Success Configuration
  paymentSuccess?: {
    title?: string;        // Custom title for payment success message (default: 'Payment Successful')
    description?: string;  // Custom description for payment success message (default: 'Thank you for your business')
  };

  // Apple Pay Configuration
  applePayEnabled?: boolean;        // Enable or disable Apple Pay
  applePayOptions?: {
    applePayMerchantId: string;     // Apple Pay merchant identifier (per merchant account, currently required, will be optional in v2)
    style?: {                        // Optional styling for the Apple Pay button
      buttonStyle?: 'black' | 'white' | 'white-outline';  // Button style
      buttonType?: string;           // Button type: pay, buy, donate, etc.
      borderRadius?: number;         // Border radius in pixels
      size?: {                       // Button size (width/height)
        width?: number | string;     // Width in px or '100%'
        height?: number | string;    // Height in px
      };
    };
  };

  // Google Pay (parent-hosted, same pattern as Apple Pay)
  googlePayEnabled?: boolean;
  googlePayOptions?: {
    googlePayMerchantId: string;
    style?: {
      buttonStyle?: 'black' | 'white' | 'white-outline';
      buttonType?: string;
      borderRadius?: number;
      size?: { width?: number | string; height?: number | string };
      locale?: string;
    };
  };

  showOnlyWalletMethods?: boolean;  // Wallet-first layout when preconditions pass

  // 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. Supported: USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY, HKD, NZD, SEK, KRW, SGD, NOK, MXN, INR, RUB, ZAR, TRY, BRL, TWD, DKK, PLN, THB, IDR, HUF, CZK, ILS, CLP, PHP, AED, COP, SAR, MYR, RON
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.campaignIdnumberNoPaysight tracking campaign identifier
data.campaignNamestringNoName (or alias/identifier) of your campaign. If campaignId is 0 and this value is provided, Paysight will auto-assign or auto-create (if new value) the campaign record
data.affiliateIdnumberNoPaysight tracking affiliate identifier
data.affiliateNamestringNoName (or alias/identifier) of your affiliate/traffic source. If affiliateId is 0 and this value is provided, Paysight will auto-assign or auto-create (if new value) the affiliate (traffic source) record
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.utm_campaignstringNoUTM campaign parameter for traffic attribution
data.utm_sourcestringNoUTM source parameter for traffic attribution
data.utm_mediumstringNoUTM medium parameter for traffic attribution
data.[key]anyNoAny additional custom data key-value pairs

Payment Success Configuration

OptionTypeDefaultDescription
paymentSuccess.titlestring’Payment Successful’Custom title for the payment success message shown after successful payment
paymentSuccess.descriptionstring’Thank you for your business’Custom description for the payment success message shown after successful payment

Apple Pay Configuration

OptionTypeRequiredDescription
applePayEnabledbooleanNoEnable or disable Apple Pay for the widget
applePayOptions.applePayMerchantIdstringYes*Apple Pay merchant identifier (per merchant account, currently required, will be optional in v2)
applePayOptions.style.buttonStyle’black’ | ‘white’ | ‘white-outline’NoButton style: black, white, or white-outline
applePayOptions.style.buttonTypestringNoButton type: pay, buy, donate, etc.
applePayOptions.style.borderRadiusnumberNoBorder radius in pixels
applePayOptions.style.size.widthnumber | stringNoButton width in pixels or ‘100%‘
applePayOptions.style.size.heightnumber | stringNoButton height in pixels
*Required when applePayEnabled is true

Google Pay configuration

OptionTypeRequiredDescription
googlePayEnabledbooleanNoEnable Google Pay (parent-hosted button on the merchant page)
googlePayOptions.googlePayMerchantIdstringYes*Google Pay merchant identifier (from Paysight)
googlePayOptions.style.buttonStyle’black’ | ‘white’ | ‘white-outline’NoGoogle Pay button color style
googlePayOptions.style.buttonTypestringNoGoogle Pay button type (e.g. pay, checkout)
googlePayOptions.style.borderRadiusnumberNoBorder radius in pixels
googlePayOptions.style.size.widthnumber | stringNoButton width in pixels or %
googlePayOptions.style.size.heightnumber | stringNoButton height in pixels
googlePayOptions.style.localestringNoOptional locale for the Google Pay button
*Required when googlePayEnabled is true

Wallet-only layout

OptionTypeRequiredDescription
showOnlyWalletMethodsbooleanNoWhen true, may hide the card form and “OR” divider until a wallet is ready; falls back to full card UI if no wallet is available or after a wallet payment error. Requires at least one of Apple or Google Pay to be fully configured.

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: {
    campaignId: 0,
    campaignName: 'summer_sale',   // Auto-assigns/creates campaign when campaignId is 0
    affiliateId: 0,
    affiliateName: 'facebook',     // Auto-assigns/creates affiliate when affiliateId is 0
    subAffiliateId: 'Primary1_Secondard2',
    clickId: 'clk_123xyz',
    utm_campaign: 'summer_sale',
    utm_source: 'facebook',
    utm_medium: 'cpc'
  },
  
  // 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'
    }
  },
  
  // Payment success message customization
  paymentSuccess: {
    title: 'Order Complete!',
    description: 'Your order has been processed successfully.'
  },
  
  // Apple Pay configuration
  applePayEnabled: true,
  applePayOptions: {
    applePayMerchantId: 'merchant_xxxxxxxx',
    style: {
      buttonStyle: 'black',
      buttonType: 'pay',
      borderRadius: 8,
      size: {
        width: '100%',
        height: 48
      }
    }
  },
  
  // 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