Configuration Guide

The Paysight Widget is highly configurable to meet your business needs. This guide covers required parameters, customer data handling, optional settings, and best practices for a robust integration.

Required Parameters

productId

number

required

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

productId: 7900 // or input your own created productId from Paysight Dashboard

sessionId

string

required

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

sessionId: 'unique-session-id'

amount

number

required

The payment amount in the selected currency. 1.00 = $1.00 is the default value for testing or a specified amount for live testing (e.g. 14.99 = $14.99).

amount: 1.00 // $1.00

environment

string

required

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

environment: 'production' // or 'sandbox'

Semi-Required Customer Data

The following customer fields are semi-required. They can be provided either via the customer object or as fields in the fields array.

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.

This string is only required if the country is US.

Optional Parameters

threeDSRequired

boolean

default:"false"

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

failOnThreeDSChallenge

boolean

default:"false"

Do not display 3DS challenge if set to true. Proceed to payment without 3DS.

cancelOnThreeDSFailure

boolean

default:"false"

Cancel the payment if the 3DS not successfully completed.

ecom

boolean

default:"false"

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

Currently not supported in the widget. Stay tuned for updates on this feautre.

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.Supported currencies: USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY, HKD, NZD, SEK, KRW, SGD, NOK, MXN, INR, RUB, ZAR, TRY, BRL, TWD, DKK, PLN, THB, IDR, HUF, CZK, ILS, CLP, PHP, AED, COP, SAR, MYR, RON

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.

paymentSuccess

object

Payment success message configuration. After successful payment, a payment complete message is shown with a title and description.

paymentSuccess.title

string

default:"Payment Successful"

Custom title for the payment success message. Overrides the default “Payment Successful” text.

paymentSuccess.description

string

default:"Thank you for your business"

Custom description for the payment success message. Overrides the default “Thank you for your business” text.

paymentSuccess: {
  title: 'Order Complete!',
  description: 'Your order has been processed successfully.'
}

applePayEnabled

boolean

Enable or disable Apple Pay for the widget.

applePayOptions

object

Apple Pay configuration options for enabling Apple Pay payments.

applePayOptions.applePayMerchantId

string

required

Apple Pay merchant identifier (per merchant account). This is the merchant ID registered with Apple Pay. Currently required, will be optional in v2.

applePayOptions.style

object

Optional styling for the Apple Pay button.

applePayOptions.style.buttonStyle

'black' | 'white' | 'white-outline'

Button style: black, white, or white-outline.

applePayOptions.style.buttonType

string

Button type: pay, buy, donate, etc.

applePayOptions.style.borderRadius

number

Border radius in pixels.

applePayOptions.style.size

object

Button size — width in px or ‘100%’, height in px.

applePayOptions.style.size.width

number | string

Button width in pixels or ‘100%’.

applePayOptions.style.size.height

number | string

Button height in pixels.

applePayEnabled: true,
applePayOptions: {
  applePayMerchantId: 'merchant_xxxxxxxx',
  style: {
    buttonStyle: 'black',
    buttonType: 'pay',
    borderRadius: 8,
    size: {
      width: '100%',
      height: 48
    }
  }
}

googlePayEnabled

boolean

Enable Google Pay. The Google Pay button is mounted on the host page above the iframe (parent-hosted). See Google Pay via Widget.

googlePayOptions

object

Google Pay configuration when googlePayEnabled is true.

googlePayOptions.googlePayMerchantId

string

required

Google Pay merchant identifier (from Paysight). Required when Google Pay is enabled.

googlePayOptions.style

object

Optional styling for the Google Pay button.

googlePayOptions.style.buttonStyle

'black' | 'white' | 'white-outline'

Button style for the hosted Google Pay button.

googlePayOptions.style.buttonType

string

Button type, e.g. pay, checkout.

googlePayOptions.style.borderRadius

number

Border radius in pixels.

googlePayOptions.style.locale

string

Optional locale for the Google Pay button.

googlePayOptions.style.size

object

googlePayOptions.style.size.width

number | string

Button width in pixels or a percentage string.

googlePayOptions.style.size.height

number | string

Button height in pixels.

googlePayEnabled: true,
googlePayOptions: {
  googlePayMerchantId: 'merchant_xxx',
  style: {
    buttonStyle: 'black',
    buttonType: 'pay',
    borderRadius: 8,
    size: { width: '100%', height: 48 },
    locale: 'en',
  },
}

showOnlyWalletMethods

boolean

When true, the checkout can show only Apple Pay and/or Google Pay (wallet buttons on the host page) and hide the card form, custom fields, and primary pay button inside the iframe—plus hide the horizontal “OR” divider—if at least one configured wallet is available. If no wallet is usable, readiness times out, or a wallet payment fails, the widget falls back to the full card UI. User cancellation of the wallet sheet does not by itself expand the card form.Requires applePayEnabled / applePayOptions and/or googlePayEnabled / googlePayOptions to be fully set when you want wallet-only mode.

For a focused walkthrough (layout, fallbacks, code sample), see Wallet-only checkout.

dev

boolean

Developer-only flag for extra diagnostics in some flows. Do not enable in production unless directed by Paysight.

disabledCardTypes

array

Disable specific card types from being used in the payment.Supported values:

visa
mastercard
american-express
discover
diners
jcb

disabledCardTypes: ['american-express']

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
}

Wallet buttons on the host page

Apple Pay and Google Pay render outside the iframe. When you enable either wallet in config, also supply container ids to createWidget (vanilla) or to the React <Widget /> component:

applePayContainerId — default slot id apple-pay-slot
googlePayContainerId — default slot id google-pay-slot

The vanilla SDK can create the wallet stack and slots if the elements are missing. See Google Pay via Widget and Apple Pay via Widget.

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: [
  {
    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

It is recommended to put a real ZIP code if you were to test live MIDs due to Address Verification Service (AVS) check, which is a fraud prevention measure used for processing credit card transactions.

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.

Theme Configuration

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: {
    '.ps-field-input' : {
      borderRadius: '8px',
      border: '1px solid #e5e7eb'
    },
    '.ps-submit' : {
      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.

See the Styling Guide for detailed theme customization options.

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
}

Google tracking parameters (gclid, wbraid, and gbraid) are automatically captured from URL parameters when available, but can also be manually specified.

Feature-Specific Configuration

Custom Button Text
Merchant ID Override

You can customize the text displayed on the payment button to better match your brand voice or the specific action being taken.

The custom button feature allows you to replace the default “Pay Now” text with your own text, such as “Complete Purchase”, “Subscribe”, or “Donate Now”.

Default Button Text

By default, the payment button displays “Pay Now” or its localized equivalent based on the selected locale.You can customize the text displayed on the payment button using the buttonText property:

  const config = {
  // ... other fields
    buttonText: 'Complete Purchase' // Custom button text
  };

This allows you to:

Match the button text to your specific use case (e.g., “Subscribe”, “Donate”, “Pay Now”)
Maintain consistent language across your application
Improve conversion rates with action-oriented text

const widget = PaySightSDK.createWidget({
  targetId: 'payment-form',
  config: {
    productId: 1234,
    sessionId: 'unique-session-id',
    amount: 29.99, // $29.99
    environment: 'production',
    fields: [
      {
        label: 'Email Address',
        placeholder: 'Enter your email',
        fieldType: 'email',
        position: 'above',
        size: 'full',
        required: true
      }
    ],
    buttonText: 'Subscribe Now' // Custom button text for subscription
  }
});

The button text will automatically update when the payment is processing to indicate the current state.

For advanced use cases, you can override the default merchant ID using the midOverride property:

  const config = {
    // ... other fields
    midOverride: 'MERCHANT_123' // Override merchant ID
  };

This feature is useful for:

Multi-merchant platforms
White-label solutions
Testing specific merchant configurations

const widget = PaySightSDK.createWidget({
  targetId: 'payment-form',
  config: {
    productId: 1234,
    sessionId: 'unique-session-id',
    amount: 99.99, // $99.99
    environment: 'production',
      fields: [
        {
          label: 'Email Address',
          placeholder: 'Enter your email',
          fieldType: 'email',
          position: 'above',
          size: 'full',
          required: true
        }
      ],
      midOverride: 'MERCHANT_123' // Use specific merchant ID
  }
});

Complete Configuration Example

Full HTML 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: 'sandbox',
        amount: 1.00,
        
        // Pre-filled customer data
        customer: {
          email: 'customer@example.com',
          firstName: 'John',
          lastName: 'Doe',
          state: 'CA',
          country: 'US'
        },

        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,
        failOnThreeDSChallenge: false,
        cancelOnThreeDSFailure: false,
        currency: 'USD',
        locale: 'en-US',
        buttonText: 'Pay Now',
        
        // Payment success message customization
        paymentSuccess: {
          title: 'Payment Complete!',
          description: 'Thank you for your purchase.'
        },
        
        // Apple Pay configuration
        applePayEnabled: true,
        applePayOptions: {
          applePayMerchantId: 'merchant_xxxxxxxx',
          style: {
            buttonStyle: 'black',
            buttonType: 'pay',
            borderRadius: 8,
            size: {
              width: '100%',
              height: 48
            }
          }
        },
        
        // 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: '00000',
          country: 'US'
        }
      });
    }
  </script>
</body>
</html>

Configuration Best Practices

Validate Required Fields

Always ensure all required fields are provided with valid values.

Missing or invalid required fields will prevent the widget from initializing properly.

Use Unique Session IDs

Generate a unique session ID for each payment attempt to prevent duplicate charges and ensure proper tracking.

  // Generate a unique session ID
  const sessionId = `session_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;

Implement Error Handling

Always provide an onError handler to catch and respond to configuration errors.

onError: (error) => {
  console.error('Configuration error:', error);
  showErrorMessage(`Payment form error: ${error.message}`);
}

Test Configuration Changes

When updating configuration dynamically, test all possible combinations to ensure a smooth user experience.

  // Update configuration based on user selection
  document.getElementById('currency-selector').addEventListener('change', (e) => {
    const selectedCurrency = e.target.value;
      widget.update({ currency: selectedCurrency });
  });

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

When prompted for 3DS authentication in test mode, use any value to complete the process.

Next Steps

Wallet-only checkout

Hide the card form and lead with Apple Pay and/or Google Pay.

Event Handling

Understand how to handle widget events for a complete integration.

Google Pay via Widget

Parent-hosted Google Pay setup and testing.

Styling Guide

Learn how to customize the widget appearance to match your brand.

Localization Guide

Implement multi-language support for global customers.

Widget SDK

Integration Guides

Widget SDK Reference

Examples

Widget Configuration

Required Parameters

Semi-Required Customer Data

Optional Parameters

Wallet buttons on the host page

Fields Configuration

Theme Configuration

Additional Data

Feature-Specific Configuration

Default Button Text

Complete Configuration Example

Configuration Best Practices

Successful Payment

Failed Payment

Visa (Credit)

Mastercard (Credit)

Visa

Mastercard

American Express

Visa

Mastercard

American Express

Visa

Mastercard

American Express

Visa

Mastercard

American Express

Next Steps

Wallet-only checkout

Event Handling

Google Pay via Widget

Styling Guide

Localization Guide

Widget SDK

Integration Guides

Widget SDK Reference

Examples

Documentation Index

​Widget Configuration

​Required Parameters

​Semi-Required Customer Data

​Optional Parameters

​Wallet buttons on the host page

​Fields Configuration

​Theme Configuration

​Additional Data

​Feature-Specific Configuration

​Default Button Text

​Complete Configuration Example

​Configuration Best Practices

Successful Payment

Failed Payment

Visa (Credit)

Mastercard (Credit)

Visa

Mastercard

American Express

Visa

Mastercard

American Express

Visa

Mastercard

American Express

Visa

Mastercard

American Express

​Next Steps

Wallet-only checkout

Event Handling

Google Pay via Widget

Styling Guide

Localization Guide

Widget Configuration

Required Parameters

Semi-Required Customer Data

Optional Parameters

Wallet buttons on the host page

Fields Configuration

Theme Configuration

Additional Data

Feature-Specific Configuration

Default Button Text

Complete Configuration Example

Configuration Best Practices

Next Steps