Event Handling

Event System Overview

Events are handled through the onMessage callback provided during widget initialization:

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

Each event message has a consistent structure:

interface WidgetMessage<T = unknown> {
  // Event type identifier
  type: string;
  
  // Event data (varies by event type)
  payload: T;
}

Each event message has a consistent structure:

interface WidgetMessage<T = unknown> {
  // Event type identifier
  type: string;
  
  // Event data (varies by event type)
  payload: T;
}

The PaySight Widget communicates with your application through a series of events during key stages of the payment process:

Widget Initialization: The widget sends a READY event when it’s fully loaded and ready to accept input.
Form Interaction: As users interact with the form, events like FORM_FIELD_CHANGE and FORM_VALIDATION are triggered.
Payment Processing: When a payment is submitted, events like PAYMENT_START, PAYMENT_SUCCESS, or PAYMENT_ERROR are sent.
3D Secure (if enabled): Additional events for 3DS authentication flow.

Event Types

Lifecycle Events

Events related to the widget’s lifecycle:

// Widget Ready - Fired when the widget is fully loaded and ready
{
  type: 'READY',
  payload: void
}

// Widget Destroyed - Fired when the widget is destroyed
{
  type: 'DESTROY',
  payload: void
}

Payment Events

Events related to the payment process:

// Payment Started - Fired when payment processing begins
{
  type: 'PAYMENT_START',
  payload: void
}

// Payment Successful - Fired when payment is completed successfully
{
  type: 'PAYMENT_SUCCESS',
  payload: {
    transactionId: string;
    amount: number;
    currency: string;
  }
}

// Payment Error - Fired when payment processing fails
{
  type: 'PAYMENT_ERROR',
  payload: {
    code: string;
    message: string;
    details?: unknown;
  }
}

3D Secure Events

Events related to 3DS verification:

// 3DS Started - Fired when 3DS verification begins
{
  type: 'PAYMENT_3DS_START',
  payload: void
}

// 3DS Successful - Fired when 3DS verification is successful
{
  type: 'PAYMENT_3DS_SUCCESS',
  payload: void
}

// 3DS Error - Fired when 3DS verification encounters an error
{
  type: 'PAYMENT_3DS_ERROR',
  payload: {
    code: string;
    message: string;
    details?: unknown;
  }
}

// 3DS Failed - Fired when 3DS verification fails
{
  type: 'PAYMENT_3DS_FAILURE',
  payload: {
    code: string;
    message: string;
    details?: unknown;
  }
}

Form Events

Events related to form interactions:

// Field Change - Fired when a form field value changes
{
  type: 'FIELD_CHANGE',
  payload: {
    field: string;
    value: unknown;
  }
}

// Field Blur - Fired when a form field loses focus
{
  type: 'FIELD_BLUR',
  payload: {
    field: string;
    value: unknown;
  }
}

// Form Submit - Fired when the form is submitted
{
  type: 'FORM_SUBMIT',
  payload: Record<string, unknown>
}

Implementing Event Handlers

const widget = PaySightSDK.createWidget({
  targetId: 'widget-container',
  config: { /* ... */ },
  onMessage: (message) => {
    switch (message.type) {
      case 'PAYMENT_SUCCESS':
        handlePaymentSuccess(message.payload);
        break;
      case 'PAYMENT_ERROR':
        handlePaymentError(message.payload);
        break;
      case 'PAYMENT_3DS_START':
        show3DSLoadingUI();
        break;
      case 'FORM_SUBMIT':
        handleFormSubmit(message.payload);
        break;
    }
  }
});

const widget = PaySightSDK.createWidget({
  targetId: 'widget-container',
  config: { /* ... */ },
  onMessage: (message) => {
    switch (message.type) {
      case 'PAYMENT_SUCCESS':
        handlePaymentSuccess(message.payload);
        break;
      case 'PAYMENT_ERROR':
        handlePaymentError(message.payload);
        break;
      case 'PAYMENT_3DS_START':
        show3DSLoadingUI();
        break;
      case 'FORM_SUBMIT':
        handleFormSubmit(message.payload);
        break;
    }
  }
});

// Event handlers
const eventHandlers = {
  // Lifecycle events
  READY: () => {
    console.log('Widget is ready');
    hideLoadingUI();
  },
  
  DESTROY: () => {
    console.log('Widget destroyed');
    cleanupResources();
  },

  // Payment events
  PAYMENT_START: () => {
    console.log('Payment started');
    showLoadingUI();
  },
  
  PAYMENT_SUCCESS: (payload) => {
    console.log('Payment successful:', payload);
    const { transactionId, amount, currency } = payload;
    showSuccessUI(amount, currency);
    // Redirect to success page or show success message
  },
  
  PAYMENT_ERROR: (payload) => {
    console.error('Payment failed:', payload);
    const { code, message } = payload;
    showErrorUI(message);
  },

  // 3DS events
  PAYMENT_3DS_START: () => {
    console.log('3DS verification started');
    show3DSLoadingUI();
  },
  
  PAYMENT_3DS_SUCCESS: () => {
    console.log('3DS verification successful');
    hide3DSLoadingUI();
  },
  
  PAYMENT_3DS_ERROR: (payload) => {
    console.error('3DS verification error:', payload);
    hide3DSLoadingUI();
    showErrorUI(payload.message);
  },

  // Form events
  FIELD_CHANGE: (payload) => {
    console.log('Field changed:', payload);
    const { field, value } = payload;
    updateFormState(field, value);
  },
  
  FORM_SUBMIT: (payload) => {
    console.log('Form submitted:', payload);
    // Handle form data
  }
};

// Initialize widget with event handling
const widget = PaySightSDK.createWidget({
  targetId: 'widget-container',
  config: { /* ... */ },
  onMessage: (message) => {
    const handler = eventHandlers[message.type];
    if (handler) {
      handler(message.payload);
    }
  }
});

interface WidgetMessage<T = unknown> {
  type: string;
  payload: T;
}

interface PaymentSuccessPayload {
  transactionId: string;
  amount: number;
  currency: string;
}

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

// Type-safe event handler
const handleMessage = (message: WidgetMessage) => {
  switch (message.type) {
    case 'PAYMENT_SUCCESS':
      const successPayload = message.payload as PaymentSuccessPayload;
      handlePaymentSuccess(successPayload);
      break;
    case 'PAYMENT_ERROR':
      const errorPayload = message.payload as PaymentErrorPayload;
      handlePaymentError(errorPayload);
      break;
  }
};

Best Practices

Handle Critical Events

Always implement handlers for these critical events:

const criticalEvents = [
  'PAYMENT_SUCCESS',
  'PAYMENT_ERROR',
  'PAYMENT_3DS_ERROR',
  'ERROR'
];

const widget = PaySightSDK.createWidget({
  onMessage: (message) => {
    if (criticalEvents.includes(message.type)) {
      handleCriticalEvent(message);
    }
  }
});

Implement Error Recovery

const handleError = (error) => {
  // Log error for debugging
  console.error('Widget error:', error);

  // Show user-friendly error message
  showErrorUI(error.message);

  // Attempt recovery based on error type
  if (error.code === 'COMMUNICATION_ERROR') {
    retryConnection();
  }
};

Maintain UI State

const updateUIState = (message) => {
  switch (message.type) {
    case 'PAYMENT_START':
      showLoadingState();
      break;
    case 'PAYMENT_SUCCESS':
      showSuccessState();
      break;
    case 'PAYMENT_ERROR':
      showErrorState();
      break;
  }
};

Provide User Feedback

Always update your UI based on event messages to keep users informed about the payment process status.

Common Event Handling Patterns

Redirect After Payment

onMessage: (message) => {
  if (message.type === 'PAYMENT_SUCCESS') {
    // Show success message
    showSuccessMessage();
    
    // Redirect to order confirmation page
    setTimeout(() => {
      window.location.href = `/confirmation?orderId=${orderId}&transactionId=${message.payload.transactionId}`;
    }, 1000);
  }
}

Updating Order Status

onMessage: async (message) => {
  if (message.type === 'PAYMENT_SUCCESS') {
    // Update order status in your system
    try {
      await updateOrderStatus(orderId, 'paid', message.payload.transactionId);
      showSuccessMessage('Payment successful! Your order has been confirmed.');
    } catch (error) {
      // Handle order update error
      console.error('Failed to update order status:', error);
      showWarningMessage('Payment successful, but order status update failed. Please contact support.');
    }
  }
}

Next Steps

Styling Guide - Learn how to customize the widget appearance
Localization Guide - Implement multi-language support
Examples - View implementation examples
Events Reference - Complete events documentation

Getting Started

Widget SDK

CRM Guides

Event Handling

Event Handling

Event System Overview

Event Types

Implementing Event Handlers

Best Practices

Redirect After Payment

Updating Order Status

Next Steps

Getting Started

Widget SDK

CRM Guides

​Event Handling

​Event System Overview

​Event Types

​Implementing Event Handlers

​Best Practices

​Next Steps

Event Handling

Event System Overview

Event Types

Implementing Event Handlers

Best Practices

Next Steps