​
At a Glance

SectionWhat’s Covered
Core APIWidget instantiation and main methods
ConfigurationWidgetConfig options, types, and parameters
Events & MessagesSupported event types and message structure
State ManagementWidget state and lifecycle
Error HandlingError types, codes, and best practices
Usage ExamplesIntegration, customization, and error flows

​
Paysight Widget SDK API Reference

Welcome to the comprehensive Paysight Widget SDK API reference. This document details all core methods, configuration options, events, type definitions, error handling, and usage patterns to build secure, customizable payment integrations.

​
Core API

​
createWidget, WidgetOptions and Widget

Create a new Paysight Widget instance:
  function createWidget(options: WidgetOptions): Widget;

​
WidgetConfig

Defines the options for configuring how the widget behaves, collects data, and appears. 
interface WidgetConfig {
  // Required fields
  productId: string;
  sessionId: string;
  amount: number;

  // Optional fields
  environment?: 'production' | 'sandbox' | 'local';
  currency?: string;
  locale?: string;
  threeDSRequired?: boolean;
  ecom?: boolean;
  theme?: WidgetTheme;
  customer?: CustomerMetadata;
  fields?: FieldConfig[];
  data?: Record<string, any>;
  buttonText?: string;
  midOverride?: string;

  // Additional options
  metadata?: Record<string, any>;
}

​
Events & Message Types

The widget communicates state and important actions through events. 
type WidgetEventType =
  | 'READY'
  | 'DESTROY'
  | 'PAYMENT_START'
  | 'PAYMENT_SUCCESS'
  | 'PAYMENT_ERROR'
  | 'PAYMENT_3DS_START'
  | 'PAYMENT_3DS_SUCCESS'
  | 'PAYMENT_3DS_ERROR'
  | 'PAYMENT_3DS_FAILURE'
  | 'VALIDATION_ERROR'
  | 'NETWORK_ERROR';
Event TypeDescription
READYThe widget has fully loaded and is ready for user input or payment initiation.
DESTROYThe widget has been removed from the page and its resources have been cleaned up.
PAYMENT_STARTA payment process has begun, typically after the user submits the payment form.
PAYMENT_SUCCESSThe payment was successfully authorized and completed.
PAYMENT_ERRORThere was an error processing the payment e.g., decline, network, or system error.
PAYMENT_3DS_START3D Secure authentication flow has started for the payment (if required/available).
PAYMENT_3DS_SUCCESS3D Secure authentication completed successfully.
PAYMENT_3DS_ERRORAn error occurred during the 3D Secure authentication process.
PAYMENT_3DS_FAILURE3D Secure authentication failed (user challenge failed or was rejected).
VALIDATION_ERRORThe user’s input did not pass validation (fields missing or formatted incorrectly).
NETWORK_ERRORThe widget could not complete a server request due to network connectivity problems.

​
State Management

interface WidgetState {
  ready: boolean;
  loading: boolean;
  valid: boolean;
  dirty: boolean;
  errors: WidgetError[];
  fields: {
    [fieldName: string]: {
      value: string;
      valid: boolean;
      error?: string;
    };
  };
}

​
Error Handling

Use the onError callback to handle errors and integrate with your app’s UI/UX. 
interface WidgetError {
  type: 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'PAYMENT_ERROR' | 'ERROR' | 'SYSTEM_ERROR';
  code: string;
  message: string;
  details?: any;
}

​
Type Definitions

Add/override form fields to control data collection.
type FieldType = 'card' | 'expiry' | 'cvv' | 'email' | 'name' | 'phone';

interface FieldConfig {
  type: FieldType;
  required?: boolean;
  position?: 'above' | 'below';
  size?: 'full' | 'half';
  validation?: {
    pattern?: string;
    message?: string;
  };
}

​
Parameters

​
type
card | expiry | cvv | email | name | phone
required
Defines the type of input field rendered. Use for collecting card, contact, or user details.
​
required
boolean
If true, the field is mandatory for form submission; if false/undefined, field is optional.
​
position
above | below
Places the field label above or below the input box for layout control.
​
size
full | half
Defines the field’s width: full spans container, half allows fields side-by-side.
​
validation
object (pattern?: string, message?: string)
Custom validation: supply a RegExp pattern and an error message for extra input checks.

​
Usage Examples

const widget = PaysightSDK.createWidget({
  targetId: 'widget-container',
  config: {
    productId: 'prod_123',
    sessionId: 'session_123',
    amount: 29.99,
    currency: 'USD'
  },
  onReady: () => console.log('Widget ready'),
  onError: (error) => console.error('Widget error:', error),
  onMessage: (message) => console.log('Message:', message)
});

​
Next Steps

Basic Integration Example

Simple implementation example

Custom Styling Example

Customize widget appearance

3DS Integration Example

3D Secure implementation

Error Handling Example

Advanced error handling
For detailed configuration options, field extensions, and advanced use cases, see related guides above. Always test with sandbox credentials before launching live payments.