​
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

SectionDescription
ConfigurationWidgetConfig interface, parameter reference
InstantiationHow to create and control your widget instance
Error HandlingError codes, troubleshooting, recovery actions
Environmentslocal, sandbox, production
Advanced TopicsTheming, 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

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

CodeMeaningTypical CauseHow to Fix
INVALID_CONFIGInvalid widget configurationMissing/incorrect WidgetConfigReview parameter requirements
INVALID_MERCHANTMerchant not found or not permittedBad merchant ID, account setupCheck your productId/midOverride
INVALID_ENVIRONMENTBad environment valueTypo in ‘environment’ fieldUse ‘production’ or ‘sandbox’
INVALID_LOCALELocale not foundLocale value in config is not recognized or supportedUse only supported values (e.g., ‘en-US’, ‘fr-FR’)
INVALID_CURRENCYCurrency not foundCurrency code is missing, misspelled or unsupportedSet a valid ISO currency code (e.g., ‘USD’, ‘EUR’)
INVALID_URLInvalid widget URLWidget endpoint URL is malformed or points to disallowed originCheck the endpoint URL, use official sandbox or production endpoints
CONFIGURATION_ERRORConfiguration error occurredWidgetConfig is missing required fields or parameters are in invalid formatReview WidgetConfig: ensure all required settings are present and valid.
INITIALIZATION_ERRORWidget failed to initializeBad targetId or environmentCheck DOM and endpoint usage
COMMUNICATION_ERRORCommunication with widget failedBad or missing config fieldsCheck all required config values
VALIDATION_ERRORValidation failed (e.g., email, amount)Invalid field or payloadCheck form field content
CONTEXT_ERRORContext error occurredWrong environment or missing targetUse browser, valid container/ID
UNKNOWN_ERRORUnexpected/unknown errorRare/edge casesCheck SDK logs and contact support
Always test your implementation in the sandbox environment before switching to production.

​
Environment Endpoints

EnvironmentEndpoint URL
Localhttp://localhost:3001/widget
Sandboxhttps://payment.paysight.io/widget
Productionhttps://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.