Skip to main content
The Paysight Widget SDK allows you to embed secure payment processing directly into your website or application. This guide will walk you through the implementation process step by step.

​
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 a Paysight product. Create a product by clicking this card.

Website Access

Access to modify the HTML/JavaScript of your website.

HTTPS

A website that uses HTTPS for secure communication.

​
Implementation Steps

1

Add the SDK to your page

Include the Paysight Widget SDK in your HTML:
<script src="https://payment.paysight.io/widget-sdk.js"></script>
If using a framework (React, Vue, Angular, etc.), load the script via your framework’s asset loader or <head> component.
2

Create a container

Add a container element where the widget will be rendered:
<div id="payment-container"></div>
3

Initialize the widget

Configure and initialize the widget with your settings:
const widget = PaysightSDK.createWidget({
  targetId: 'payment-container',
  config: {
    // Required parameters
    productId: 7900, // Replace with your actual product ID
    sessionId: 'unique-session-id',
    environment: 'sandbox', // Use 'production' for live MIDs
    amount: 1.00, // 1.00 USD should be the default amount for testing purposes

    // Pre-filled customer data (optional)
    customer: {
      email: 'customer@example.com',
      firstName: 'John',
      lastName: 'Doe',
      state: 'CA', // Required if country is US
      country: 'US' // Always required, two capital letters (e.g. US, UK)
    },

    // Additional fields (optional)
    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: false, // Only set to true if required (for NON-US MIDs)
    failOnThreeDSChallenge: false, // Do not display 3DS challenge if set to true. Proceed to payment without 3DS.
    cancelOnThreeDSFailure: false, // Cancel the payment if the 3DS not successfully completed.
    currency: 'USD',
    locale: 'en-US'
  },
  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);
    }
  }
});
Replace productId with your actual product ID from your Paysight account.amount should be a decimal (e.g. 1.00 for $1.00).country is always required (two-letter code, uppercase, e.g. US or UK).state is required for US transactions (two-letter code, e.g. CA).Use a real zip code for best approval rates.Email is not required in fields if provided in the customer object.threeDSRequired should be set to false by default. Set it to true for non-US MIDs.failOnThreeDSChallenge should be set to false by default. Set to true if you want to proceed to payment without 3DS.cancelOnThreeDSFailure should be set to false by default. Set to true if you want to cancel the payment if the 3DS not successfully completed.locale must be in the format xx-XX (e.g. en-US, fr-FR | 'language'-'COUNTRY').
See supported locales
4

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;
  }
};
You can access all relevant transaction, customer and card data in the message.payload object.
{
  "paysightSession": "202506261406197480118249333",
  "partnerSession": "484589cf-346b-4f2b-a910-947b126865b4",
  "subscribeSuccess": false,
  "chargeSuccess": false,
  "info": "Error",
  "error": "Failed",
  "email": "john.doe@example.com",
  "message": "",
  "orderId": 193924815,
  "descriptor": "",
  "mid": "383",
  "transactionId": "e676fc0f-1ada-4c86-bc36-320b90ee5af3",
  "amount": 1,
  "statusId": 0,
  "declineSalvage": false,
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "12345"
  },
  "card": {
    "bin": "54625332",
    "lastFour": "1234",
    "brand": "mastercard"
  },
  "extra": {
  "locale": "en-US",
  "currency": "USD"
  }
}
When handling payment events, always log or inspect the full message.payload object. This gives you access to all transaction, customer, and card details for debugging.
See the Events Guide for a complete list of events and payload details.
5

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'
  }
});
Updating customer data does not auto-update UI fields if already rendered.

​
Prefill vs. Fields: Two Approaches

You can either prefill customer data using the customer object (fields are hidden and prefilled), or collect data from the user using the fields array.You can also mix both—prefill some fields and collect others.
Key points:
  • If you provide an email in the customer object, you do not need an email field in fields. The payment button will be enabled as long as a valid email is present in either source.
  • The more customer data you provide, the better the chance of transaction approval.

​
Testing Your Integration

1

Use test mode

Set the environment to 'sandbox' for testing:
environment: 'sandbox'
2

Use Test Cards in Sandbox

When testing in the sandbox environment, use specific test cards to simulate various payment scenarios:
  • Basic Testing
  • NMI Test Cards PANs
  • More Test Cards

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
3

Check your test transactions

View your test transactions in the Paysight dashboard under Transactions

​
Next Steps

Configuration Guide

Explore all configuration options for the widget.

Event Handling

Learn how to handle all widget events.

Styling Guide

Customize the widget appearance to match your brand.
For a complete reference of all Widget SDK features and options, see the Technical Reference.