API Reference

This document provides a comprehensive reference for the PaySight Widget SDK API, including all available methods, events, and types.

Core API

createWidget

Creates a new instance of the PaySight Widget.

function createWidget(options: WidgetOptions): Widget;

interface WidgetOptions {
  targetId: string;
  config: WidgetConfig;
  onReady?: () => void;
  onError?: (error: WidgetError) => void;
  onMessage?: (message: WidgetMessage) => void;
}

Parameters

targetId (string) - ID of the HTML element where the widget will be mounted
config (WidgetConfig) - Widget configuration options
onReady (function, optional) - Callback when widget is ready
onError (function, optional) - Error handler callback
onMessage (function, optional) - Message handler callback

Returns

Returns a Widget instance with the following methods:

interface Widget {
  update(config: Partial<WidgetConfig>): void;
  destroy(): void;
  reset(): void;
  validate(): Promise<boolean>;
  getState(): WidgetState;
}

update

Updates the widget configuration.

widget.update({
  amount: 1999,
  currency: 'EUR'
});

destroy

Destroys the widget instance and removes it from the DOM.

widget.destroy();

reset

Resets the widget to its initial state.

widget.reset();

validate

Validates the current widget state.

const isValid = await widget.validate();

getState

Returns the current widget state.

const state = widget.getState();

Configuration

WidgetConfig

Configuration options for the widget.

interface WidgetConfig {
  // Required fields
  productId: string;
  sessionId: string;
  amount: number;
  
  // Optional fields
  environment?: 'production' | 'sandbox' | 'local';
  currency?: string;
  locale?: string;
  threeDSRequired?: boolean;
  ecom?: boolean;
  
  // Styling
  theme?: WidgetTheme;
  
  // Customer data
  customer?: {
    email?: string;
    name?: string;
    phone?: string;
  };
  
  // Additional options
  metadata?: Record<string, any>;
}

WidgetTheme

Theme configuration for customizing the widget appearance.

interface WidgetTheme {
  font?: string;
  css?: {
    [selector: string]: {
      [property: string]: string | number;
    };
  };
}

Events

Event Types

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';

WidgetMessage

Structure of messages received in the onMessage callback.

interface WidgetMessage {
  type: WidgetEventType;
  payload?: any;
  timestamp: number;
}

Event Payloads

Payment Success

interface PaymentSuccessPayload {
  transactionId: string;
  amount: number;
  currency: string;
  status: 'success';
  timestamp: number;
}

Payment Error

interface PaymentErrorPayload {
  code: string;
  message: string;
  details?: any;
}

3DS Events

interface ThreeDSPayload {
  threeDSId: string;
  status: '3ds_started' | '3ds_completed' | '3ds_failed';
  details?: any;
}

Error Handling

Error Types

interface WidgetError {
  type: 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'PAYMENT_ERROR' | 'ERROR' | 'SYSTEM_ERROR';
  code: string;
  message: string;
  details?: any;
}

Error Codes

Common error codes returned by the widget:

Code	Description
`VALIDATION_INVALID_CARD`	Invalid card number
`VALIDATION_EXPIRED_CARD`	Card has expired
`VALIDATION_INVALID_CVV`	Invalid CVV code
`NETWORK_CONNECTION_ERROR`	Network connection failed
`NETWORK_TIMEOUT`	Network request timed out
`PAYMENT_DECLINED`	Payment was declined
`PAYMENT_3DS_FAILED`	3D Secure verification failed
`INITIALIZATION_ERROR`	Widget failed to initialize
`CONFIG_ERROR`	Invalid widget configuration

State Management

WidgetState

Structure of the widget state object.

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

Type Definitions

Field Types

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;
  };
}

Theme Types

interface ThemeColors {
  primary: string;
  error: string;
  text: string;
  background: string;
  border: string;
}

interface ThemeSpacing {
  sm: string;
  md: string;
  lg: string;
}

interface ThemeTypography {
  fontFamily: string;
  fontSize: string;
  fontWeight: string;
}

Usage Examples

Basic Integration

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

Custom Styling

const widget = PaySightSDK.createWidget({
  // ... other options
  config: {
    // ... other config
    theme: {
      font: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap',
      css: {
        input: {
          borderRadius: '8px',
          fontSize: '15px'
        },
        button: {
          backgroundColor: '#6366f1'
        }
      }
    }
  }
});

Error Handling

function handleError(error: WidgetError) {
  switch (error.type) {
    case 'VALIDATION_ERROR':
      showValidationError(error.message);
      break;
    case 'NETWORK_ERROR':
      retryPayment();
      break;
    case 'PAYMENT_ERROR':
      handlePaymentFailure(error);
      break;
    default:
      showGenericError();
  }
}

State Management

function checkWidgetState() {
  const state = widget.getState();
  
  if (!state.valid) {
    console.log('Invalid fields:', state.errors);
    return;
  }
  
  if (state.loading) {
    console.log('Widget is processing payment');
    return;
  }
  
  // Proceed with payment
  console.log('Widget is ready for payment');
}

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

Widget SDK Reference

Examples

Paysight API

Email Services

Payment API

Customer Service API

Admin API

Mitigation API

​API Reference

​Core API

​createWidget

​Parameters

​Returns

​Widget Methods

​update

​destroy

​reset

​validate

​getState

​Configuration

​WidgetConfig

​WidgetTheme

​Events

​Event Types

​WidgetMessage

​Event Payloads

​Payment Success

​Payment Error

​3DS Events

​Error Handling

​Error Types

​Error Codes

​State Management

​WidgetState

​Type Definitions

​Field Types

​Theme Types

​Usage Examples

​Basic Integration

​Custom Styling

​Error Handling

​State Management

​Next Steps

API Reference

Core API

createWidget

Parameters

Returns

Widget Methods

update

destroy

reset

validate

getState

Configuration

WidgetConfig

WidgetTheme

Events

Event Types

WidgetMessage

Event Payloads

Payment Success

Payment Error

3DS Events

Error Handling

Error Types

Error Codes

State Management

WidgetState

Type Definitions

Field Types

Theme Types

Usage Examples

Basic Integration

Custom Styling

Error Handling

State Management

Next Steps