Technical Reference

Comprehensive implementation guide for the Paysight Widget SDK, including configuration, interfaces, error handling and endpoints

Paysight Widget SDK Technical Reference

The Paysight Widget SDK enables you to embed secure, customizable payment forms into any website, with seamless CRM integration and full developer control.

Start with a working example, see our Quick Start Guide for a step by step setup.

---

At a Glance

Section	Description
Configuration	WidgetConfig interface, parameter reference
Instantiation	How to create and control your widget instance
Error Handling	Error codes, troubleshooting, recovery actions
Environments	local, sandbox, production
Advanced Topics	Theming, localization, advanced usage, examples

---

SDK Architecture

The Paysight Widget SDK is built on a message-based architecture that enables secure communication between your application and the widget iframe.

The SDK handles:

• Cross-origin communication
• Configuration validation
• Event management
• State synchronization
• Resource management
• Security measures

---

Integration Examples

Quick Integration

createWidget({
  targetId: 'payment-widget',
  config: {
    productId: 1234,
    sessionId: 'unique-session-id',
    amount: 1.00,
    environment: 'sandbox',
    locale: 'en-US'
  },
  onReady: () => console.log('Widget ready!'),
  onError: error => console.error(error)
});

Each transaction session requires a unique sessionId to ensure security and track activity.

---

Widget Configuration

productId · number · required

Your Paysight product ID

sessionId · string · required

Unique session identifier

amount · number · required

Charge amount (in cents)

environment · string · required

‘production’, ‘sandbox’ or ‘local’

threeDSRequired · boolean · default: "false"

Require 3D Secure authentication

ecom · boolean

Ecommerce payment flag

fields · FieldConfig[]

Custom form fields configuration

customer · CustomerMetadata

Pre-fill customer data

data · object

Additional custom/tracking data

theme · WidgetTheme

UI theme options

Our styling options has specified classes, check them here at Styling Guide

locale · SupportedLocale · default: "en-US"

Widget display localization

Check all supported locales

currency · SupportedCurrency · default: "USD"

Payment currency

buttonText · string

Payment button text

midOverride · string

Override merchant account ID

See the Configuration Guide for complete details and real-world usage patterns.

---

Key Interfaces

WidgetConfig

interface WidgetConfig {
  productId: number;
  sessionId: string;
  amount: number;
  environment: 'production' | 'sandbox' | 'local';
  threeDSRequired?: boolean;
  ecom?: boolean;
  fields?: FieldConfig[];
  customer?: CustomerMetadata;
  data?: { [key: string]: any };
  theme?: WidgetTheme;
  locale?: SupportedLocale;
  currency?: SupportedCurrency;
  buttonText?: string;
  midOverride?: string;
}

Additional Interfaces:

• FieldConfig: Custom field setup (label, placeholder, type, size, position).

Check more about FieldConfig field types at API Reference

• CustomerMetadata: Pre-fill customer info (email, phone, address, etc.).
• WidgetTheme: Light/dark mode, font, CSS specified custom classes.

---

Widget Instance & Lifecycle

Creating a Widget Instance

interface CreateWidgetOptions {
  targetId: string;
  config: WidgetConfig;
  onError?: (error: MessageError) => void;
  onReady?: () => void;
  onMessage?: (message: WidgetMessage) => void;
  minHeight?: number;
}

• update(updates: Partial<WidgetConfig>): Live-update widget config.
• destroy(): Cleanup widget resources after use.

Bind error and event handlers for robust integration and easier troubleshooting.

---

Error Handling

Error Structure

Code	Meaning	Typical Cause	How to Fix
INVALID_CONFIG	Invalid widget configuration	Missing/incorrect WidgetConfig	Review parameter requirements
INVALID_MERCHANT	Merchant not found or not permitted	Bad merchant ID, account setup	Check your productId/midOverride
INVALID_ENVIRONMENT	Bad environment value	Typo in ‘environment’ field	Use ‘production’ or ‘sandbox’
INVALID_LOCALE	Locale not found	Locale value in config is not recognized or supported	Use only supported values (e.g., ‘en-US’, ‘fr-FR’)
INVALID_CURRENCY	Currency not found	Currency code is missing, misspelled or unsupported	Set a valid ISO currency code (e.g., ‘USD’, ‘EUR’)
INVALID_URL	Invalid widget URL	Widget endpoint URL is malformed or points to disallowed origin	Check the endpoint URL, use official sandbox or production endpoints
CONFIGURATION_ERROR	Configuration error occurred	WidgetConfig is missing required fields or parameters are in invalid format	Review WidgetConfig: ensure all required settings are present and valid.
INITIALIZATION_ERROR	Widget failed to initialize	Bad targetId or environment	Check DOM and endpoint usage
COMMUNICATION_ERROR	Communication with widget failed	Bad or missing config fields	Check all required config values
VALIDATION_ERROR	Validation failed (e.g., email, amount)	Invalid field or payload	Check form field content
CONTEXT_ERROR	Context error occurred	Wrong environment or missing target	Use browser, valid container/ID
UNKNOWN_ERROR	Unexpected/unknown error	Rare/edge cases	Check SDK logs and contact support

Always test your implementation in the sandbox environment before switching to production.

---

Environment Endpoints

Environment	Endpoint URL
Local	http://localhost:3001/widget
Sandbox	https://payment.paysight.io/widget
Production	https://payment.paysight.io/widget

Use test credentials and test productIds while developing in the sandbox environment.

---

Next Steps

Widget Configuration Guide

Explore all configuration options for the widget.

Events Reference

Reference for events and handling.

Core Concepts

Explore the core concepts of our Widget SDK

Basic Integration Example

Have a look at a simple integration and you can use it to get ideas, try other features.

By following this reference and exploring the linked guides, you can rapidly build secure, fully integrated payment experiences, tailored to your own web platform.