​
Events Reference

This document provides a comprehensive reference for all events emitted by the PaySight Widget SDK, including their types, payloads, and handling patterns.

​
Event System Overview

The PaySight Widget uses an event-driven architecture to communicate state changes, user interactions, and payment processing status. Events are handled through the onMessage callback provided during widget initialization.

const widget = PaySightSDK.createWidget({
  targetId: 'widget-container',
  config,
  onMessage: (message: WidgetMessage) => {
    console.log('Event received:', message.type);
  }
});

​
Widget Events Reference

​
Event Types

The PaySight Widget emits various events during its lifecycle. Here’s a comprehensive list of all available events:

​
Widget Lifecycle Events

  • READY - Emitted when the widget is fully loaded and ready to accept input
  • MOUNT - Emitted when the widget is mounted to the DOM
  • UNMOUNT - Emitted when the widget is unmounted from the DOM
  • HEIGHT_CHANGE - Emitted when the widget’s height changes
  • FOCUS - Emitted when a field in the widget receives focus
  • BLUR - Emitted when a field in the widget loses focus

​
Payment Events

  • PAYMENT_START - Emitted when payment processing begins
  • PAYMENT_SUCCESS - Emitted when payment is successful
  • PAYMENT_ERROR - Emitted when payment fails
  • PAYMENT_CANCEL - Emitted when payment is cancelled

​
3D Secure Events

  • PAYMENT_3DS_START - Emitted when 3DS verification begins
  • PAYMENT_3DS_SUCCESS - Emitted when 3DS verification is successful
  • PAYMENT_3DS_ERROR - Emitted when 3DS verification encounters an error
  • PAYMENT_3DS_FAILURE - Emitted when 3DS verification fails
  • PAYMENT_3DS_CANCEL - Emitted when 3DS verification is cancelled

​
Validation Events

  • VALIDATION_ERROR - Emitted when field validation fails
  • VALIDATION_SUCCESS - Emitted when field validation succeeds

​
Network Events

  • NETWORK_ERROR - Emitted when a network request fails
  • NETWORK_SUCCESS - Emitted when a network request succeeds

​
Event Payloads

Each event type includes a specific payload structure:

interface WidgetEvent<T = any> {
  type: string;
  payload: T;
}

interface ValidationErrorPayload {
  field: string;
  message: string;
  code: string;
}

interface PaymentErrorPayload {
  message: string;
  code: string;
  details?: Record<string, any>;
}

interface NetworkErrorPayload {
  message: string;
  status: number;
  details?: Record<string, any>;
}

interface ThreeDSPayload {
  status: string;
  message?: string;
  details?: Record<string, any>;
}

​
Event Handling Example

const widget = createWidget({
  // ... widget configuration ...
  onMessage: (event) => {
    switch (event.type) {
      case 'READY':
        console.log('Widget is ready');
        break;
      
      case 'PAYMENT_START':
        showLoadingUI();
        break;
      
      case 'PAYMENT_SUCCESS':
        handleSuccess(event.payload);
        break;
      
      case 'PAYMENT_ERROR':
        handleError(event.payload);
        break;
      
      case 'PAYMENT_3DS_START':
        show3DSVerificationUI();
        break;
      
      case 'VALIDATION_ERROR':
        showFieldError(event.payload);
        break;
    }
  }
});

​
Best Practices

  1. Always handle critical events like PAYMENT_ERROR and VALIDATION_ERROR
  2. Provide appropriate user feedback for each event type
  3. Implement proper error recovery mechanisms
  4. Log events for debugging purposes
  5. Handle network errors gracefully
  6. Manage widget state based on events

​
Event Debugging

Enable debug mode to see detailed event logs:

const widget = createWidget({
  debug: true,
  onMessage: (event) => {
    console.log('Widget event:', event.type, event.payload);
  }
});

​
Next Steps