Skip to main content
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: 'customer@example.com',
      firstName: 'Jane',
      lastName: 'Doe',
      country: 'US',
      state: 'CA',
    },
    fields: [
      {
        label: 'Email',
        placeholder: 'you@example.com',
        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:
OptionPurpose
customerOptional prefill — seeds values into the form or payment request. Omit fields you want the shopper to enter.
fieldsRequired 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: 'customer@example.com', country: 'US' },
fields: [
  { label: 'Email', placeholder: 'you@example.com', 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

FieldTypeNotes
productIdnumberNot a string
amountnumberDecimal major units (29.99), not cents
environment'sandbox' | 'production'Use sandbox for testing, production for live
customer.countrystringTwo-letter ISO code, often required
fieldsFieldConfig[]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