Widget SDK Quick Start Guide

Prerequisites

Before you begin integrating the Widget SDK, ensure you have:

Paysight Account

An active Paysight merchant account. Contact your account manager to get access.

Product ID

A product ID from from a Paysight product. Create a product here

Website Access

Access to modify the HTML/JavaScript of your website.

HTTPS

A website that uses HTTPS for secure communication.

Implementation Steps

Add the SDK to your page

Include the Paysight Widget SDK in your HTML:

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

Create a container

Add a container element where the widget will be rendered:

<div id="payment-container"></div>

Initialize the widget

Configure and initialize the widget with your settings:

const widget = PaySightSDK.createWidget({
  targetId: 'payment-container',
  config: {
    // Required parameters
    productId: YOUR_PRODUCT_ID,
    sessionId: 'unique-session-id',
    environment: 'production',
    amount: 2.99,
    
    // Pre-filled customer data
    customer: {
      email: 'customer@example.com',
      firstName: 'John',
      lastName: 'Doe',
      state: 'CA',
      country: 'US'
    },
    
    // Required email field and additional fields
    fields: [
      {
        {/* Email Field is currently required */}
        label: 'Email Address',
        placeholder: 'Enter your email',
        fieldType: 'email',
        position: 'above',
        size: 'full',
      },
      {/* Full Name Field is currently semi-required, can be skipped if you're passing the customer object */}
      {
        label: 'Full Name',
        placeholder: 'Enter your full name',
        fieldType: 'name',
        position: 'above',
        size: 'full'
      },
      {/* Full Name Field is currently semi-required, can be skipped if you're passing the customer object */}
      {
        label: 'Country',
        placeholder: 'Select your country',
        fieldType: 'country',
        position: 'above',
        size: 'half'
      },
      {/* Full Name Field is currently semi-required, can be skipped if you're passing the customer object */}
      {
        label: 'State/Province',
        placeholder: 'Enter your state',
        fieldType: 'state',
        position: 'above',
        size: 'half'
      }
    ],
    
    // Optional parameters
    threeDSRequired: true,
    currency: 'USD',
    locale: 'en-US',
    
    // Additional data for tracking
    data: {
      clickId: 'campaign-123',
      gclid: 'CjwKCAiAzc2tBhA4EiwA5gFXtqxZQn8H9XdF9jKm',
      wbraid: 'CLjQ5oGVqvsCFQiNaAodgM4PqA',
      gbraid: 'CLjQ5oGVqvsCFQiNaAodgM4PqA'
    }
  },
  onReady: () => {
    console.log('Widget is ready');
  },
  onError: (error) => {
    const errorElement = document.getElementById('error-message');
    errorElement.textContent = error.message;
    errorElement.style.display = 'block';
    console.error('Widget error:', error);
  },
  onMessage: (message) => {
    if (message.type === 'PAYMENT_SUCCESS') {
      console.log('Payment successful:', message.payload);
    }
  }
});

Handle payment events

Implement event handlers to respond to payment status:

widget.onMessage = (message) => {
  switch (message.type) {
    case 'PAYMENT_SUCCESS':
      showSuccessMessage(`Payment successful! Transaction ID: ${message.payload.transactionId}`);
      break;
    case 'PAYMENT_ERROR':
      showErrorMessage(message.payload.message);
      break;
  }
};

Update customer data (if needed)

If you don’t have all required customer data at initialization, you can update it later:

// Update customer data before payment
widget.update({
  customer: {
    email: 'customer@example.com',
    firstName: 'John',
    lastName: 'Doe',
    state: 'CA',
    country: 'US'
  }
});

Complete Implementation Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>PaySight Widget Example</title>
  
  <!-- Add the PaySight Widget SDK -->
  <script src="https://payment.paysight.io/widget-sdk.js"></script>
  
  <style>
    .container {
      max-width: 600px;
      margin: 40px auto;
      padding: 20px;
    }
    .widget-container {
      border: 1px solid #e5e7eb;
      border-radius: 8px;
      padding: 20px;
    }
    .status {
      padding: 12px;
      border-radius: 6px;
      margin-bottom: 16px;
      display: none;
    }
    .error {
      background-color: #fee2e2;
      border: 1px solid #ef4444;
      color: #b91c1c;
    }
    .success {
      background-color: #dcfce7;
      border: 1px solid #22c55e;
      color: #15803d;
    }
  </style>
</head>
<body>
  <div class="container">
    <div id="success-message" class="status success"></div>
    <div id="error-message" class="status error"></div>
    <div id="widget-container" class="widget-container"></div>
  </div>

  <script>
    // Initialize widget
    const widget = PaySightSDK.createWidget({
      targetId: 'widget-container',
      config: {
        // Required parameters
        productId: 7900, // Replace with your actual product ID
        sessionId: new Date().getTime().toString(),
        environment: 'production',
        amount: 2.99,
        
        // Pre-filled customer data
        customer: {
          email: 'customer@example.com',
          firstName: 'John',
          lastName: 'Doe',
          state: 'CA',
          country: 'US'
        },
        
        // Required email field and additional fields
        fields: [
          {
            label: 'Email Address',
            placeholder: 'Enter your email',
            fieldType: 'email',
            position: 'above',
            size: 'full',
            
          },
          {
            label: 'Full Name',
            placeholder: 'Enter your full name',
            fieldType: 'name',
            position: 'above',
            size: 'full'
          },
          {
            label: 'Country',
            placeholder: 'Select your country',
            fieldType: 'country',
            position: 'above',
            size: 'half'
          },
          {
            label: 'State/Province',
            placeholder: 'Enter your state',
            fieldType: 'state',
            position: 'above',
            size: 'half'
          }
        ],
        
        // Optional parameters
        threeDSRequired: true,
        currency: 'USD',
        locale: 'en-US',
        buttonText: 'Pay Now',
        
        // Additional data for tracking
        data: {
          clickId: 'campaign-123',
          gclid: 'CjwKCAiAzc2tBhA4EiwA5gFXtqxZQn8H9XdF9jKm',
          wbraid: 'CLjQ5oGVqvsCFQiNaAodgM4PqA',
          gbraid: 'CLjQ5oGVqvsCFQiNaAodgM4PqA'
        }
      },
      onReady: () => {
        console.log('Widget is ready');
      },
      onError: (error) => {
        const errorElement = document.getElementById('error-message');
        errorElement.textContent = error.message;
        errorElement.style.display = 'block';
        console.error('Widget error:', error);
      },
      onMessage: (message) => {
        switch (message.type) {
          case 'PAYMENT_SUCCESS':
            const successElement = document.getElementById('success-message');
            successElement.textContent = `Payment successful! Transaction ID: ${message.payload.transactionId}`;
            successElement.style.display = 'block';
            break;
          case 'PAYMENT_ERROR':
            const errorElement = document.getElementById('error-message');
            errorElement.textContent = message.payload.message;
            errorElement.style.display = 'block';
            break;
        }
      }
    });
    
    // Example of updating customer data later
    function updateCustomerData() {
      widget.update({
        customer: {
          email: 'updated@example.com',
          firstName: 'Jane',
          lastName: 'Smith',
          phone: '+1234567890',
          address: '123 Main St',
          city: 'Anytown',
          state: 'NY',
          zip: '12345',
          country: 'US'
        }
      });
    }
  </script>
</body>
</html>

Configuration Options

Required Parameters

productId

number

required

Your PaySight product ID that identifies your merchant account and product configuration. 7900 can be used for testing purposes.

sessionId

string

required

A unique identifier for the payment session. This should be unique for each payment attempt.

amount

number

required

The payment amount in the selected currency.

environment

string

required

The environment to run the widget in. The options are ‘production’ and ‘sandbox’.

Required Form Fields

fields

array

required

An array of field configuration objects that define form fields. Must include an email field.

fields: [
  {
    label: 'Email Address',
    placeholder: 'Enter your email',
    fieldType: 'email',
    position: 'above',
    size: 'full',
  }
]

Semi-Required Customer Data

customer.firstName

string

Customer’s first name. Can be provided via customer object or a name field.

customer.lastName

string

Customer’s last name. Can be provided via customer object or a name field.

customer.state

string

Customer’s state/province. Can be provided via customer object or a state field.

customer.country

string

Customer’s country code (e.g., ‘US’). Can be provided via customer object or a country field.

Optional Parameters

threeDSRequired

boolean

default:"false"

Enable 3D Secure authentication for the payment. Recommended for enhanced security.

ecom

boolean

default:"false"

Enable ecommerce mode. This is used if the payment is for a ecommerce product.

locale

string

default:"en-US"

Set the language and region for the widget interface.

currency

string

default:"USD"

The currency code for the payment. Must be a valid ISO 4217 currency code.

buttonText

string

default:"Pay Now"

Custom text for the payment button. Use this to match your brand voice or specific action.

theme

object

UI theme customization options to match your brand. Includes font, colors, and styling.

midOverride

string

Override the merchant ID for the payment. Requires special permissions.

data

object

Additional custom data to include with the payment. Useful for tracking and analytics.

data: {
  clickId: 'ad-campaign-123',
  // More properties to be supported soon
}

Fields Configuration

The fields parameter allows you to customize the form fields displayed in the widget. This is useful for collecting additional information from customers or customizing the checkout experience.

fields

array

An array of field configuration objects that define custom form fields.

fields: [
  // Required email field
  {
    label: 'Email Address',
    placeholder: 'Enter your email',
    fieldType: 'email',
    position: 'above',
    size: 'full',
  },
  // Additional fields
  {
    label: 'Phone Number',
    placeholder: 'Enter your phone number',
    fieldType: 'phone',
    position: 'above',
    size: 'full'
  },
  {
    label: 'Company Name',
    placeholder: 'Enter your company name',
    fieldType: 'text',
    position: 'above',
    size: 'half'
  }
]

Each field object supports the following properties:

label

string

required

The label text displayed to the user.

placeholder

string

Placeholder text shown in the input field when empty.

fieldType

string

required

The type of field to display. Supported values:

email - Email address input with validation (required)
name - Name input field
phone - Phone number input with formatting
address - Street address input
city - City input
state - State/province input
zip - Postal/ZIP code input
country - Country selection dropdown
text - Generic text input
divider - Visual divider (not an input field)

position

string

default:"above"

Label position relative to the input field. Options: above or below.

size

string

default:"full"

Field width within the form. Options: full, half, or third.

required

boolean

default:"false"

Whether the field is required to be filled before submission.

Customer Data Pre-filling

customer

object

Pre-fill customer information to streamline the checkout process. This will populate the corresponding form fields.

customer: {
  email: 'customer@example.com',
  firstName: 'John',
  lastName: 'Doe',
  phone: '+1234567890',
  address: '123 Main St',
  city: 'San Francisco',
  state: 'CA',
  zip: '94103',
  country: 'US'
}

Theme Customization

The theme parameter allows you to customize the appearance of the widget to match your brand.

theme

object

Object containing theme customization options.

theme: {
  font: 'https://fonts.googleapis.com/css2?family=Inter',
  themeName: 'light', // or 'dark'
  css: {
    input: {
      borderRadius: '8px',
      border: '1px solid #e5e7eb'
    },
    button: {
      backgroundColor: '#5D4CFE',
      color: 'white',
      borderRadius: '8px'
    }
  }
}

theme.font

string

URL to a custom font to use in the widget. We currently support Google Fonts only. This is a beta feature.

theme.themeName

string

default:"light"

Base theme to use. Options: light or dark.

theme.css

object

Custom CSS properties for different widget elements.

Additional Data

The data parameter allows you to include custom data with the payment transaction, which is useful for tracking and analytics.

data

object

An object containing additional data to associate with the payment.

data: {
  clickId: 'click_12345',
  campaignId: 'summer-promo-2023',
  affiliateId: 'partner-001',
  gclid: 'CjwKCAiAzc2tBhA4EiwA5gFXtqxZQn8H9XdF9jKm', // Google Click Identifier
  wbraid: 'CLjQ5oGVqvsCFQiNaAodgM4PqA', // Web BRAID for Google Ads
  gbraid: 'CLjQ5oGVqvsCFQiNaAodgM4PqA', // Google BRAID for app tracking
  // Additional custom properties
}

Testing Your Integration

Use test mode

Set the environment to ‘sandbox’ for testing:

environment: 'sandbox'

Use test card numbers

In Sandbox mode, you can use specific test cards to simulate various real-life scenarios. These cards can be used with any valid expiry date and CVV.

Successful Payment

Card: 4242 4242 4242 4242 Expiry: Any future date CVV: Any 3 digits

Failed Payment

Card: 4000 0000 0000 0002 Expiry: Any future date CVV: Any 3 digits

Customization Options

Customize the appearance of the widget to match your brand:

const widget = PaySightSDK.createWidget({
  targetId: 'payment-container',
  config: {
    // Required fields
    productId: 123,
    sessionId: 'unique-session-xyz',
    amount: 2.99,
    environment: 'production',
    
    // Required email field
    fields: [
      {
        label: 'Email Address',
        placeholder: 'Enter your email',
        fieldType: 'email',
        position: 'above',
        size: 'full',
        
      }
    ],
    
    // Styling options
    theme: {
      font: 'https://fonts.googleapis.com/css2?family=Inter',
      themeName: 'light', // or 'dark'
      css: {
        input: {
          borderRadius: '8px',
          border: '1px solid #e5e7eb'
        },
        button: {
          backgroundColor: '#5D4CFE',
          color: 'white',
          borderRadius: '8px'
        }
      }
    }
  }
});

Customize the appearance of the widget to match your brand:

const widget = PaySightSDK.createWidget({
  targetId: 'payment-container',
  config: {
    // Required fields
    productId: 123,
    sessionId: 'unique-session-xyz',
    amount: 2.99,
    environment: 'production',
    
    // Required email field
    fields: [
      {
        label: 'Email Address',
        placeholder: 'Enter your email',
        fieldType: 'email',
        position: 'above',
        size: 'full',
        
      }
    ],
    
    // Styling options
    theme: {
      font: 'https://fonts.googleapis.com/css2?family=Inter',
      themeName: 'light', // or 'dark'
      css: {
        input: {
          borderRadius: '8px',
          border: '1px solid #e5e7eb'
        },
        button: {
          backgroundColor: '#5D4CFE',
          color: 'white',
          borderRadius: '8px'
        }
      }
    }
  }
});

Set the language and region for the widget:

const widget = PaySightSDK.createWidget({
  targetId: 'payment-container',
  config: {
    // Required fields
    productId: 123,
    sessionId: 'unique-session-xyz',
    amount: 2.99,
    environment: 'production',
    
    // Required email field
    fields: [
      {
        label: 'Email Address',
        placeholder: 'Enter your email',
        fieldType: 'email',
        position: 'above',
        size: 'full',
      }
    ],
    
    // Localization
    locale: 'fr-FR', // French (France)
    currency: 'EUR'
  }
});

Pre-fill customer information to streamline the checkout process:

const widget = PaySightSDK.createWidget({
  targetId: 'payment-container',
  config: {
    // Required fields
    productId: 123,
    sessionId: 'unique-session-xyz',
    amount: 2.99,
    environment: 'production',
    
    // Required email field
    fields: [
      {
        label: 'Email Address',
        placeholder: 'Enter your email',
        fieldType: 'email',
        position: 'above',
        size: 'full',
      }
    ],
    
    // Customer information (pre-fills the email field)
    customer: {
      email: 'customer@example.com',
      firstName: 'John',
      lastName: 'Doe',
      address: '123 Main St',
      city: 'San Francisco',
      state: 'CA',
      zip: '94103',
      country: 'US'
    }
  }
});

Next Steps

Configuration Guide

Explore all configuration options for the widget.

Events Guide

Learn how to handle all widget events.

Styling Guide

Customize the widget appearance to match your brand.

Getting Started

Widget SDK

CRM Guides

​Widget SDK Quick Start Guide

​Prerequisites

Paysight Account

Product ID

Website Access

HTTPS

​Implementation Steps

​Complete Implementation Example

​Configuration Options

​Required Parameters

​Required Form Fields

​Semi-Required Customer Data

​Optional Parameters

​Fields Configuration

​Customer Data Pre-filling

​Theme Customization

​Additional Data

​Testing Your Integration

Successful Payment

Failed Payment

Successful Payment

Failed Payment

Visa

Mastercard

American Express

Visa

Mastercard

American Express

Visa

Mastercard

American Express

Visa

Mastercard

American Express

​Customization Options

​Next Steps

Configuration Guide

Events Guide

Styling Guide

Prerequisites

Implementation Steps

Complete Implementation Example

Configuration Options

Required Parameters

Required Form Fields

Semi-Required Customer Data

Optional Parameters

Fields Configuration

Customer Data Pre-filling

Theme Customization

Additional Data

Testing Your Integration

Customization Options

Next Steps