​
Technical Reference

This technical reference provides detailed documentation of the PaySight Widget SDK’s APIs, interfaces, and implementation details.

​
SDK Architecture

The PaySight Widget SDK is built on a message-based architecture that enables secure communication between your application and the widget iframe. The SDK handles:

  • Cross-origin communication
  • Configuration validation
  • Event management
  • State synchronization
  • Resource management
  • Security measures

​
Core Interfaces

​
Widget Configuration

interface WidgetConfig {
  /**
   * Your PaySight product ID
   * @required
   */
  productId: number;

  /**
   * Unique session identifier
   * @required
   */
  sessionId: string;

  /**
   * Amount to charge in cents
   * @required
   */
  amount: number;

  /**
   * Environment to run the widget in
   * @required
   */
  environment: 'production' | 'sandbox' | 'local';

  /**
   * Enable 3D Secure authentication
   * @default false
   */
  threeDSRequired?: boolean;

  /**
   * Flag to indicate if this is an ecommerce payment
   * @optional
   */
  ecom?: boolean;

  /**
   * Custom form fields configuration
   * @optional
   */
  fields?: FieldConfig[];

  /**
   * Pre-fill customer data
   * @optional
   */
  customer?: CustomerMetadata;

  /**
   * Additional custom data
   * @optional
   */
  data?: {
    /**
     * PaySight campaign identifier
     * @optional
     */
    campaignId?: string;

    /**
     * PaySight affiliate identifier
     * @optional
     */
    affiliateId?: string;

    /**
     * PaySight sub-affiliate identifier
     * @optional
     */
    subAffiliateId?: string;

    /**
     * PaySight tracking click identifier
     * @optional
     */
    trackhouseClickId?: string;

    /**
     * Generic tracking click identifier
     * @optional
     */
    clickId?: string;

    /**
     * Google Click Identifier for tracking ad clicks
     * @optional
     */
    gclid?: string;

    /**
     * Web BRAID identifier for Google Ads tracking
     * @optional
     */
    wbraid?: string;

    /**
     * Google BRAID identifier for app conversion tracking
     * @optional
     */
    gbraid?: string;

    /**
     * Any additional custom data
     * @optional
     */
    [key: string]: any;
  };

  /**
   * UI theme customization
   * @optional
   */
  theme?: WidgetTheme;

  /**
   * Widget locale
   * @default 'en-US'
   * @supported 'en-US', 'en-GB', 'de-DE', 'es-ES', 'fr-FR', 'it-IT', 'pl-PL', 'pt-PT', 'ro-RO', 'ru-RU', 'tr-TR', 'fi-FI', 'no-NO'
   */
  locale?: SupportedLocale;

  /**
   * Payment currency
   * @default 'USD'
   */
  currency?: SupportedCurrency;

  /**
   * Custom text for the payment button
   * @optional
   */
  buttonText?: string;

  /**
   * Override the merchant ID for the payment
   * @optional
   */
  midOverride?: string;
}

interface FieldConfig {
  /**
   * Field label displayed to the user
   */
  label: string;

  /**
   * Placeholder text
   */
  placeholder: string;

  /**
   * Type of field
   */
  fieldType: 'name' | 'phone' | 'address' | 'city' | 'state' | 'zip' | 'email' | 'country' | 'divider';

  /**
   * Label position relative to the input
   */
  position: 'above' | 'below';

  /**
   * Field width
   */
  size: 'full' | 'half';
}

interface CustomerMetadata {
  email?: string;
  phone?: string;
  firstName?: string;
  lastName?: string;
  address?: string;
  city?: string;
  state?: string;
  zip?: string;
  country?: string;
}

interface WidgetTheme {
  font?: string;
  css?: Record<string, any>;
  themeName?: 'light' | 'dark';
}

​
Widget Instance

interface Widget {
  /**
   * Update widget configuration
   */
  update(updates: Partial<WidgetConfig>): void;

  /**
   * Destroy widget and cleanup resources
   */
  destroy(): void;
}

interface CreateWidgetOptions {
  /**
   * Target element ID where the widget iframe will be injected
   */
  targetId: string;

  /**
   * Widget configuration
   */
  config: WidgetConfig;

  /**
   * Error handler
   */
  onError?: (error: MessageError) => void;

  /**
   * Success handler
   */
  onReady?: () => void;

  /**
   * Message handler for all widget events
   */
  onMessage?: (message: WidgetMessage) => void;

  /**
   * Minimum height for the widget iframe
   */
  minHeight?: number;
}

​
Error Handling

​
Error Types

interface MessageError extends Error {
  code: string;
  details?: unknown;
}

const ERROR_CODES = {
  INVALID_CONFIG: 'Invalid widget configuration',
  INVALID_MERCHANT: 'Invalid merchant ID',
  INVALID_ENVIRONMENT: 'Invalid environment',
  INVALID_LOCALE: 'Invalid locale',
  INVALID_CURRENCY: 'Invalid currency',
  INVALID_URL: 'Invalid widget URL',
  CONFIGURATION_ERROR: 'Configuration error occurred',
  INITIALIZATION_ERROR: 'Failed to initialize widget',
  COMMUNICATION_ERROR: 'Communication with widget failed',
  VALIDATION_ERROR: 'Validation failed',
  CONTEXT_ERROR: 'Context error occurred',
  UNKNOWN_ERROR: 'An unknown error occurred'
} as const;

​
API Endpoints

The widget communicates with the following endpoints:

const URLS = {
  LOCAL: 'http://localhost:3001/widget',
  PRODUCTION: 'https://payment.paysight.io/widget',
  SANDBOX: 'https://payment.paysight.io/widget'
} as const;

​
Next Steps