Widget SDK Quick Start

Minimal embed with accurate types and amounts

This guide covers the smallest working integration. For every config option, see Configuration reference.

Prerequisites

Paysight account

An active merchant account with a configured product.

Product ID

A numeric product ID from the Paysight dashboard.

HTTPS

Production pages must use HTTPS.

Steps

1. Load the SDK

   <script src="https://payment.paysight.io/widget-sdk.js"></script>
   
2. Add a container

   <div id="payment-container"></div>
   
3. Initialize the widget

   const widget = PaySightSDK.createWidget({
     targetId: 'payment-container',
     config: {
       productId: YOUR_PRODUCT_ID,
       sessionId: 'YOUR_SESSION_ID',
       environment: 'sandbox',
       amount: 29.99,
       customer: {
         email: '[e-mail]',
         firstName: 'Jane',
         lastName: 'Doe',
         country: 'US',
         state: 'CA',
       },
       fields: [
         {
           label: 'Email',
           placeholder: '[e-mail]',
           fieldType: 'email',
           position: 'above',
           size: 'full',
         },
       ],
     },
     onReady: () => console.log('Widget ready'),
     onMessage: (message) => {
       switch (message.type) {
         case 'PAYMENT_SUCCESS':
           console.log('Paid', message.payload);
           break;
         case 'PAYMENT_ERROR':
           console.error(message.payload);
           break;
       }
     },
   });
   

Customer object vs fields

These serve different purposes:

Option	Purpose
customer	Optional prefill — seeds values into the form or payment request. Omit fields you want the shopper to enter.
fields	Required form layout — defines which inputs appear in the iframe. Your product typically requires a minimum set (e.g. email, name, country).

customer alone does not replace fields. If you omit fields, the widget uses your product’s default field requirements. If required data is missing at submit time, you receive ERROR with VALIDATION_FAILED.

Example — prefill email but still show the field:

customer: { email: '[e-mail]', country: 'US' },
fields: [
  { label: 'Email', placeholder: '[e-mail]', fieldType: 'email', position: 'above', size: 'full' },
  { label: 'Country', placeholder: 'Select country', fieldType: 'country', position: 'above', size: 'half' },
],

See Configuration guide for semi-required customer data.

Important types

Field	Type	Notes
productId	number	Not a string
amount	number	Decimal major units (29.99), not cents
environment	'sandbox' | 'production'	Use sandbox for testing, production for live
customer.country	string	Two-letter ISO code, often required
fields	FieldConfig[]	Array with fieldType, position, size

Optional: Wallet-only checkout

If you enable Apple Pay and/or Google Pay, set showOnlyWalletMethods: true to hide the card form when a wallet is available, with automatic fallback to the full card UI.

Wallet-only checkout

Requirements, layout, fallbacks, and examples.

Apple Pay via Widget

Domain verification and parent-hosted Apple Pay.

Try it live

Open playground

Interactive sandbox — edit config, watch events, copy embed code.

Playground guide

Walkthrough of all 12 presets and inspector tabs.

Next steps

Configuration

Customer prefill, fields, and full setup

Events

Handle payment, 3DS, and cart events

External button

Host your own pay CTA

Upsell flow

Two-page saved-payment checkout