> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paysight.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration Guide
> How to configure the Paysight Widget for your specific needs, with up-to-date best practices.
## 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
| 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
Your Paysight product ID (numeric) from the dashboard.
```javascript theme={null}
productId: YOUR_PRODUCT_ID
```
A unique identifier for the payment session. This should be unique for each payment attempt.
```javascript theme={null}
sessionId: 'unique-session-id'
```
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`).
```javascript theme={null}
amount: 1.00 // $1.00
```
The environment to run the widget in: `'sandbox'` or `'production'`.
```javascript theme={null}
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.
Customer's first name. Can be provided via customer object or a name field.
Customer's last name. Can be provided via customer object or a name field.
Customer's state/province. Can be provided via customer object or a state field.
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.
Do not display 3DS challenge if set to true. Proceed to payment without 3DS.
Cancel the payment if the 3DS not successfully completed.
Mark the payment as ecommerce. When `true`, the flag is sent to the Paysight API on card, wallet, and upsell payment paths.
Set the language and region for the widget interface.
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`
Custom text for the payment button. Use this to match your brand voice or specific action.
UI theme customization options to match your brand. Includes font, colors, and styling.
Override the merchant ID for the payment. Requires special permissions.
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.
```javascript theme={null}
paymentSuccess: {
title: 'Order Complete!',
description: 'Your order has been processed successfully.'
}
```
Enable or disable Apple Pay for the widget.
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.
Button style: `black`, `white`, or `white-outline`.
Button type: `pay`, `buy`, `donate`, etc.
Border radius in pixels.
Button size — width in px or '100%', height in px.
Button width in pixels or '100%'.
Button height in pixels.
```javascript theme={null}
applePayEnabled: true,
applePayOptions: {
applePayMerchantId: 'merchant_xxxxxxxx',
style: {
buttonStyle: 'black',
buttonType: 'pay',
borderRadius: 8,
size: {
width: '100%',
height: 48
}
}
}
```
Enable Google Pay. The Google Pay button is mounted on the **host page** above the iframe (parent-hosted). See [Google Pay via Widget](/widget-sdk/guides/google-pay-via-widget).
Google Pay configuration when `googlePayEnabled` is `true`.
Google Pay merchant identifier (from Paysight). Required when Google Pay is enabled.
Optional styling for the Google Pay button.
Button style for the hosted Google Pay button.
Button type, e.g. `pay`, `checkout`.
Border radius in pixels.
Optional locale for the Google Pay button.
Button width in pixels or a percentage string.
Button height in pixels.
```javascript theme={null}
googlePayEnabled: true,
googlePayOptions: {
googlePayMerchantId: 'merchant_xxx',
style: {
buttonStyle: 'black',
buttonType: 'pay',
borderRadius: 8,
size: { width: '100%', height: 48 },
locale: 'en',
},
}
```
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](/widget-sdk/guides/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:
* `visa`
* `mastercard`
* `american-express`
* `discover`
* `diners`
* `jcb`
```javascript theme={null}
disabledCardTypes: ['american-express']
```
Additional custom data to include with the payment. Useful for tracking and analytics.
```javascript theme={null}
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](/widget-sdk/guides/google-pay-via-widget) and [Apple Pay via Widget](/widget-sdk/guides/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.
An array of field configuration objects that define custom form fields.
```javascript theme={null}
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:**
The label text displayed to the user.
Placeholder text shown in the input field when empty.
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)
Label position relative to the input field. Options: `above` or `below`.
Field width within the form. Options: `full`, `half`, or `third`.
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 containing theme customization options.
```javascript theme={null}
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'
}
}
}
```
URL to a custom font to use in the widget. Google Fonts URLs are supported.
Custom CSS properties for different widget elements.
See the [Styling Guide](/widget-sdk/guides/styling) 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.
An object containing additional data to associate with the payment.
```javascript theme={null}
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
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:
```javascript theme={null}
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
```javascript Subscription theme={null}
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
}
});
```
```javascript Donation theme={null}
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:
```javascript theme={null}
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
```javascript Basic Override theme={null}
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
}
});
```
```javascript Dynamic Override theme={null}
// 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
```html theme={null}
Paysight Widget Example
```
## Configuration Best Practices
Always ensure all required fields are provided with valid values.
Missing or invalid required fields will prevent the widget from initializing properly.
Generate a unique session ID for each payment attempt to prevent duplicate charges and ensure proper tracking.
```javascript theme={null}
// Generate a unique session ID
const sessionId = `session_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
```
Always provide an `onError` handler to catch and respond to configuration errors.
```javascript theme={null}
onError: (error) => {
console.error('Configuration error:', error);
showErrorMessage(`Payment form error: ${error.message}`);
}
```
When updating configuration dynamically, test all possible combinations to ensure a smooth user experience.
```javascript theme={null}
// Update configuration based on user selection
document.getElementById('currency-selector').addEventListener('change', (e) => {
const selectedCurrency = e.target.value;
widget.update({ currency: selectedCurrency });
});
```
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.
Card: 4242 4242 4242 4242
Expiry: Any future date
CVV: Any 3 digits
Card: 4000 0000 0000 0002
Expiry: Any future date
CVV: Any 3 digits
Card: 4532 1111 1111 1112
Expiry: Any future date
CVV: First 3 digits from the card (453)
Card: 5411 1111 1111 1115
Expiry: Any future date
CVV: First 3 digits from the card (453)
You can check NMI's full Test Cards [here](https://support.nmi.com/hc/en-gb/articles/115002375583-Test-Cards). Which includes more card schemes, AVS test cards and PAR test response.
These cards will trigger a 3D-Secure challenge flow, requiring additional authentication:
Any valid Visa card
Expiry: Any future date
CVV: Any 3 digits
Any valid Mastercard
Expiry: Any future date
CVV: Any 3 digits
Any valid Amex card
Expiry: Any future date
CVV: Any 4 digits
These cards will trigger a successful 3D-Secure frictionless flow (no challenge):
4111 1101 1663 8870
Expiry: Any future date
CVV: Any 3 digits
5555 5501 3065 9057
Expiry: Any future date
CVV: Any 3 digits
3782 8224 6310 005
Expiry: Any future date
CVV: Any 4 digits
These cards will trigger a failed 3D-Secure frictionless flow:
4111 1117 3897 3695
Expiry: Any future date
CVV: Any 3 digits
5555 5504 8784 7545
Expiry: Any future date
CVV: Any 3 digits
3782 8224 6310 013
Expiry: Any future date
CVV: Any 4 digits
These cards will trigger an attempted authentication flow:
4111 1101 4848 6405
Expiry: Any future date
CVV: Any 3 digits
5555 5588 2481 5604
Expiry: Any future date
CVV: Any 3 digits
3782 8224 6310 021
Expiry: Any future date
CVV: Any 4 digits
When prompted for 3DS authentication in test mode, use any value to complete the process.
## Next Steps
Hide the card form and lead with Apple Pay and/or Google Pay.
Understand how to handle widget events for a complete integration.
Parent-hosted Google Pay setup and testing.
Learn how to customize the widget appearance to match your brand.
Implement multi-language support for global customers.