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.

Customer object vs fields

Option	Role
`customer`	Optional prefill — seeds known values (email, name, address). Omit any field you want the shopper to type.
`fields`	Required form layout — controls which inputs render in the iframe. Your Paysight product defines minimum required data.

Prefilling customer does not skip validation. If required data is missing at submit, the widget emits ERROR with VALIDATION_FAILED and missingFields.

You can supply semi-required data via customer, via fields, or both — values from customer pre-populate matching fields when present.

Required Parameters

number

required

Your Paysight product ID (numeric) from the dashboard.

productId: YOUR_PRODUCT_ID

string

required

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

sessionId: 'unique-session-id'

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

string

required

The environment to run the widget in: 'sandbox' or 'production'.

environment: 'sandbox' // use 'production' for live payments

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.

string

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

string

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

string

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

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

boolean

default:"false"

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

boolean

default:"false"

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

boolean

default:"false"

Cancel the payment if the 3DS not successfully completed.

boolean

default:"false"

Mark the payment as ecommerce. When true, the flag is sent to the Paysight API on card, wallet, and upsell payment paths.

string

default:"en-US"

Set the language and region for the widget interface.

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

string

default:"Pay Now"

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

object

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

string

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

object

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

string

default:"Payment Successful"

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

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.'
}

boolean

Enable or disable Apple Pay for the widget.

object

Apple Pay configuration options for enabling Apple Pay payments.

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.

object

Optional styling for the Apple Pay button.

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

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

string

Button type: pay, buy, donate, etc.

number

Border radius in pixels.

object

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

number | string

Button width in pixels or ‘100%’.

number | string

Button height in pixels.

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

boolean

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

object

Google Pay configuration when googlePayEnabled is true.

string

required

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

object

Optional styling for the Google Pay button.

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

Button style for the hosted Google Pay button.

string

Button type, e.g. pay, checkout.

number

Border radius in pixels.

string

Optional locale for the Google Pay button.

object

number | string

Button width in pixels or a percentage string.

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',
  },
}

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.

boolean

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

array

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

visa
mastercard
american-express
discover
diners
jcb

disabledCardTypes: ['american-express']

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:

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.

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:

string

required

The label text displayed to the user.

string

Placeholder text shown in the input field when empty.

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)

string

default:"above"

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

string

default:"full"

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

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.

object

Object containing theme customization options.

theme: {
  font: 'https://fonts.googleapis.com/css2?family=Inter',
  css: {
    '.ps-field-input' : {
      borderRadius: '8px',
      border: '1px solid #e5e7eb'
    },
    '.ps-submit' : {
      backgroundColor: '#5D4CFE',
      color: 'white',
      borderRadius: '8px'
    }
  }
}

string

URL to a custom font to use in the widget. Google Fonts URLs are supported.

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.

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
  }
});

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

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
  }
});

// Function to get merchant ID based on user selection
const getMerchantId = (selectedMerchant) => {
  const merchantMap = {
    'store1': 'MERCHANT_123',
    'store2': 'MERCHANT_456',
    'store3': 'MERCHANT_789'
  };
  return merchantMap[selectedMerchant] || defaultMerchantId;
};
// Use in widget configuration
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: getMerchantId(selectedMerchant)
  }
});

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="apple-pay-slot"></div>
  <div id="google-pay-slot"></div>
  <div id="widget-container" class="widget-container"></div>
</div>

<script>
  const widget = PaySightSDK.createWidget({
    targetId: 'widget-container',
    applePayContainerId: 'apple-pay-slot',
    googlePayContainerId: 'google-pay-slot',
    config: {
        // Required parameters
        productId: YOUR_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
            }
          }
        },

        googlePayEnabled: true,
        googlePayOptions: {
          googlePayMerchantId: 'merchant_xxxxxxxx',
          style: {
            buttonStyle: 'black',
            buttonType: 'pay',
            borderRadius: 8,
            size: { width: '100%', height: 48 },
            locale: 'en',
          },
        },
        
        // 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

Customer object vs fields

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

​Customer object vs fields

​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

Customer object vs fields

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