​
At a Glance

SectionDescription
ArchitectureWidget isolation and communication model
Widget InstanceCreating, updating, destroying the widget
ConfigurationKey settings, fields, appearance parameters
SecurityPCI, 3D Secure, real-time validation
State ManagementWidget lifecycle, event handling
Best PracticesError management, resource cleanup

​
Architecture Overview

Paysight Widget SDK is architected for secure, modular, and efficient payment integration within any web application. This document covers the fundamental principles, structure, and key best practices for leveraging the SDK to its fullest.

​
Secure iFrame Integration

All payment flow occurs within a secure iFrame embedded on your site:
  • PCI DSS compliant—no payment data on your servers
  • Cross-origin isolation prevents data leakage
  • Simple, drop-in code to add to your app
Sensitive payment data always remains in the Paysight environment, your site never sees or stores card information.

​
Message Based Communication

  • Uses browser postMessage API for all widget–parent communication
  • Bi-directional: Send config, receive results/events
  • Only validated, type-safe messages are permitted
  • Enables real-time UI updates, event-based flows, and analytics

​
Widget Instance

This is the main interface for controlling the payment widget:
Initialization: Attach to a DOM element via targetId
const widget = PaysightSDK.createWidget({
  targetId: 'container',
  config: {
    /* See Configuration section / },
    onMessage: (message) => { / handle events / },
    onError: (error) => { / handle errors */ 
  }
});

​
Configuration

Control the widget’s behavior and appearance using WidgetConfig. 
const config = {
  productId: 1234, // required
  sessionId: 'unique-session', // required
  amount: 1.00, // required
  environment: 'sandbox', // required: 'production', 'sandbox', or 'local'
  threeDSRequired: true, // optional, default: false
  currency: 'USD', // optional, default: 'USD'
  locale: 'en-US', // optional, default: 'en-US'
  theme: { /* ... */ }, // optional theming
  fields: [ /* ... */ ], // optional form customization
  customer: { email: 'dev@site.com' }, // optional prefill
  data: { gclid: 'abc123' } // optional tracking/metadata
};
Check the Widget Configuration field types at Technical Reference - Widget Configuration

​
Field and Theme Customization

fields: [
  { label: 'Shipping Info', fieldType: 'divider' },
  { label: 'Name', fieldType: 'name', position: 'above', size: 'full' },
  { label: 'Phone', fieldType: 'phone', position: 'above', size: 'half' }
]
Supported field types: name, email, phone, address, city, state, zip, country, divider.

​
Event System

Receive payment results and state changes through event handlers: 
widget.onMessage = (message) => {
  switch (message.type) {
    case 'PAYMENT_SUCCESS':
    // Payment completed
    break;
    case 'PAYMENT_ERROR':
    // Handle error
    break;
    case 'FIELD_CHANGE':
    // Field edited
    break;
    case 'PAYMENT_START':
    // Payment started
    break;
  }
};
  • onMessage: Receives state changes (payment, fields, status)
  • onError: Catches integration errors
Always bind both onMessage and onError to ensure you catch all outcomes and errors during integration.

​
Security & Compliance

  • PCI DSS Compliant: Sensitive card data is managed inside Paysight’s secure iFrame—not on your infrastructure.
  • 3D Secure Support: Enable with threeDSRequired: true, handled automatically by the widget.
    • Example:
      const config = {
    threeDSRequired: true,
    // Widget handles the complete 3DS flow
  };
  • Real-Time Validation: All data and messages are validated before processing.
  • Safe by Design: Only trusted origins can exchange data with the widget.
Never store, log, or transmit cardholder data outside the Paysight widget.

​
State Management

​
Widget Lifecycle Steps

  1. Initialize: 
    const widget = PaysightSDK.createWidget({ ... });
  2. Update config dynamically: 
    widget.update({ amount: 20.00 });
  3. Cleanup: 
    widget.destroy();
State and updates are isolated; interaction is managed by public config and event interfaces.

​
Best Practices

  • Use a unique sessionId for each transaction—improves security and reporting.
  • Always register onError and handle errors defensively.
  • Call destroy() when you remove the widget, especially in single-page apps.
  • Test integration fully in the sandbox environment before production launch.
  • For best developer experience, use TypeScript to benefit from the provided interfaces.
    • Example:
    interface PaymentSuccessPayload {
  transactionId: string;
  amount: number;
  currency: string;
}
onMessage: (message: WidgetMessage) => {
  if (message.type === 'PAYMENT_SUCCESS') {
    const payload = message.payload as PaymentSuccessPayload;
    handleSuccess(payload);
  }
}

​
Troubleshooting

For more on error codes and integration troubleshooting, visit the Widget SDK Troubleshooting Guide.
Common Problems:
  • Initialization errors → double-check required config fields.
  • Cross-origin/messaging errors → verify origin and CSP.
  • Form validation errors → confirm types and supported locales.

​
Next Steps

Widget Configuration Guide

Explore all configuration options for the widget.

Events Reference

Reference for events and handling.

Styling Guide

Check all supported CSS classes from our Styling Guide.

Troubleshooting

Diagnose and resolve common issues you may encounter when using Paysight Widget SDK
Understanding these principles will help you create robust, secure, and flexible payment experiences with the Paysight Widget SDK.