Widget Configuration
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
Prefilling
customer does not skip validation. If required data is missing at submit, the widget emits ERROR with VALIDATION_FAILED and missingFields.customer, via fields, or both — values from customer pre-populate matching fields when present.
Required Parameters
A unique identifier for the payment session. This should be unique for each payment attempt and no more than 50 characters. It is forwarded to Card Submit as
partnerSession.The payment amount in decimal major units of the configured currency (e.g.
14.99). The SDK requires this field: amount: 0 uses the subscription immediate charge attached to the Paysight product, when set; amount > 0 overrides it. Zero does not request a free payment. This pricing behavior and the Shopify cart exception are explained in Initial and upsell pricing.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’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
Enable 3D Secure authentication for the payment. Recommended for enhanced security.
Mark the payment as ecommerce. When
true, the flag is sent to the Paysight API on card, wallet, and upsell payment paths.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, RONCustom text for the payment button. Use this to match your brand voice or specific action.
Payment success message configuration. After successful payment, a payment complete message is shown with a title and description.
Custom title for the payment success message. Overrides the default “Payment Successful” text.
Custom description for the payment success message. Overrides the default “Thank you for your business” text.
Apple Pay configuration options for enabling Apple Pay payments.
Apple Pay merchant identifier (per merchant account). This is the merchant ID registered with Apple Pay. Currently required, will be optional in v2.
Optional styling for the Apple Pay button.
Enable Google Pay. The Google Pay button is mounted on the host page above the iframe (parent-hosted). See Google Pay via Widget.
Google Pay configuration when
googlePayEnabled is true.Optional styling for the Google Pay button.
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.
Developer-only flag for extra diagnostics in some flows. Do not enable in production unless directed by Paysight.
Disable specific card types from being used in the payment.Supported values:
visamastercardamerican-expressdiscoverdinersjcb
String key-value data to include with the payment. Use the recognized attribution keys for campaign and affiliate reporting; other keys are forwarded as custom metadata.Do not send
campaignId or affiliateId. These are deprecated, internal Paysight identifiers rather than free-form metadata. See Tracking & attribution.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 idapple-pay-slotgooglePayContainerId— default slot idgoogle-pay-slot
Fields Configuration
Thefields 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.
Each field object supports the following properties:
The type of field to display. Supported values:
email- Email address input with validation (required)name- Name input fieldphone- Phone number input with formattingaddress- Street address inputcity- City inputstate- State/province inputzip- 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 dropdowntext- Generic text inputdivider- Visual divider (not an input field)
Theme Configuration
Thetheme parameter allows you to customize the appearance of the widget to match your brand.
Custom CSS properties for different widget elements.
See the Styling Guide for detailed theme customization options.
Additional Data
Thedata parameter allows you to include string key-value data with the payment transaction. Recognized keys receive dedicated attribution handling; other keys are forwarded as custom metadata and may require account-specific reporting configuration.
An object containing additional data to associate with the payment.
Google tracking parameters (
gclid, wbraid, and gbraid) are automatically captured from URL parameters when available, but can also be manually specified.Feature-Specific Configuration
- Merchant ID Override
Complete Configuration Example
Full HTML Example
Full HTML Example
Configuration Best Practices
1
Validate Required Fields
Always ensure all required fields are provided with valid values.
2
Use Unique Session IDs
Generate a unique session ID for each payment attempt to prevent duplicate charges and ensure proper tracking.
3
Implement Error Handling
Always provide an
onError handler to catch and respond to configuration errors.4
Test Configuration Changes
When updating configuration dynamically, test all possible combinations to ensure a smooth user experience.
5
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.
- Basic Testing
- NMI Test Cards PANs
- 3DS Challenge Flow
- 3DS Successful Frictionless
- 3DS Failed Frictionless
- 3DS Attempted Auth
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.