​
Core Concepts

The PaySight Widget SDK is built on several core concepts that are essential to understand for effective integration and usage.

​
Architecture Overview

​
Secure iFrame Integration

The widget runs in a secure iFrame, isolating the payment form from your main application. This architecture:

  • Ensures PCI compliance
  • Prevents sensitive data exposure
  • Maintains security across origins
  • Enables seamless integration

​
Message-Based Communication

Communication between your application and the widget occurs through a secure message-based system:

  • Events are passed via postMessage
  • All messages are validated and origin-checked
  • Type-safe payload structures
  • Bi-directional communication

​
Key Components

​
Widget Instance

The main interface for interacting with the payment form:

const widget = PaySightSDK.createWidget({
  targetId: 'container',
  config: { /* ... */ },
  onMessage: (message) => { /* ... */ }
});

​
Configuration

Controls the widget’s behavior and appearance:

const config = {
  // Required settings
  productId: 12345,
  sessionId: 'unique-id',
  amount: 2999,
  environment: 'production',
  
  // Optional features
  threeDSRequired: true,
  theme: { /* ... */ },
  fields: [ /* ... */ ]
};

​
Event System

Handles all communication with the widget:

widget.onMessage = (message) => {
  switch (message.type) {
    case 'PAYMENT_SUCCESS':
      // Handle successful payment
      break;
    case 'PAYMENT_ERROR':
      // Handle payment error
      break;
  }
};

​
Core Features

​
Payment Processing

The widget handles the complete payment flow:

  1. Card data collection
  2. Validation
  3. 3D Secure verification (when required)
  4. Payment processing
  5. Result communication

​
Form Customization

Flexible form field configuration:

const config = {
  fields: [
    {
      label: 'Shipping Information',
      fieldType: 'divider'
    },
    {
      label: 'Name',
      fieldType: 'name',
      position: 'above',
      size: 'full'
    }
  ]
};

​
Theming System

Comprehensive styling capabilities:

const config = {
  theme: {
    font: 'https://fonts.googleapis.com/css2?family=Inter',
    css: {
      input: {
        borderRadius: '6px',
        border: '1px solid #e5e7eb'
      }
    }
  }
};

​
Security Features

​
PCI Compliance

  • Sensitive data handled in secure iFrame
  • No card data touches your servers
  • Compliant with PCI DSS requirements

​
3D Secure

Built-in 3DS support:

const config = {
  threeDSRequired: true,
  // Widget handles the complete 3DS flow
};

​
Data Validation

  • Real-time field validation
  • Type-safe configurations
  • Secure message validation

​
State Management

​
Widget Lifecycle

  1. Initialization

    const widget = PaySightSDK.createWidget(options);

  2. Configuration Updates

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

  3. Cleanup

    widget.destroy();

​
Event-Driven Updates

The widget maintains its own state and communicates changes through events:

onMessage: (message) => {
  switch (message.type) {
    case 'FIELD_CHANGE':
      // Form field updated
      break;
    case 'PAYMENT_START':
      // Payment process started
      break;
    case 'PAYMENT_SUCCESS':
      // Payment completed
      break;
  }
}

​
Best Practices

​
Error Handling

Implement comprehensive error handling:

const widget = PaySightSDK.createWidget({
  onError: (error) => {
    console.error('Widget Error:', {
      code: error.code,
      message: error.message,
      details: error.details
    });
  }
});

​
Resource Management

Clean up resources when the widget is no longer needed:

// Remove widget and clean up resources
widget.destroy();

​
Type Safety

Use TypeScript for better development experience:

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

onMessage: (message: WidgetMessage) => {
  if (message.type === 'PAYMENT_SUCCESS') {
    const payload = message.payload as PaymentSuccessPayload;
    handleSuccess(payload);
  }
}

​
Next Steps