Configuration reference

All options are passed in the config object of PaySightSDK.createWidget.

amount uses decimal major units (29.99). productId is a number. When shopify is set, pass amount: 0 — totals are computed from cart lines.

Required fields

number

required

Paysight product ID from your dashboard. Use the same ID for the initial payment and every upsell in the customer journey; it is not a per-offer catalog ID.

string

required

Unique identifier per checkout attempt (you generate this), up to 50 characters. The Widget forwards it to Card Submit as partnerSession.

number

required

Charge amount in decimal major units; this field is required. For normal card payments, amount: 0 uses the immediate charge configured on the subscription attached to the Paysight product, when set. An amount greater than zero overrides that immediate charge and sets the initial payment amount. Zero must not be used to request a free payment. Each upsell can set its own amount. Ignored when shopify is set (use 0 for cart-computed totals).See Initial and upsell pricing.

'sandbox' | 'production'

required

sandbox for testing, production for live payments.

Customer and fields

CustomerMetadata

Optional prefill — values merged into the form and payment request. Does not replace visible fields.

Field	Type
`email`	`string`
`phone`	`string`
`firstName`	`string`
`lastName`	`string`
`address`	`string` (street)
`city`	`string`
`state`	`string`
`zip`	`string`
`country`	`string` (two-letter ISO, required for many flows)

FieldConfig[]

Form layout — inputs rendered in the iframe. Product requirements determine the minimum set.

{
  label: string;
  placeholder: string;
  fieldType: 'name' | 'phone' | 'address' | 'city' | 'state' | 'zip' | 'email' | 'country' | 'divider';
  position: 'above' | 'below';  // relative to card form
  size: 'full' | 'half';
}

CardType[]

Card brands to hide. Values: visa, mastercard, american-express, discover, diners, jcb, maestro, unionpay.

3D Secure

boolean

Require 3DS when supported.

boolean

Cancel payment when 3DS fails.

boolean

Treat 3DS challenge as failure.

Per-upsell overrides: upsell.threeDSRequired, upsell.cancelOnThreeDSFailure, upsell.failOnThreeDSChallenge.

Saved payment & upsell

boolean

On checkout, ask the API to store the payment method for a later charge. Works on card, Apple Pay, and Google Pay.

boolean

Charge using the stored method. Requires upsell.initialPaymentSession (the paysightSession from page 1).

UpsellConfig

Configuration for each upsell in the chain. Active when both upsellId and initialPaymentSession are set. Reuse the initial checkout’s top-level productId and original successful paysightSession for every upsell.upsellId can be any nonempty string (upsell-1, upsell-product-name). Use a different ID for each offer in the journey and retain it for retries of that offer. It participates in duplicate detection and widget events; transaction APIs currently do not return it.

{
  upsellId: string;
  initialPaymentSession: string;  // paysightSession from PAYMENT_SUCCESS
  upsellButton?: { text?: string; style?: StyleObject };
  threeDSRequired?: boolean;
  cancelOnThreeDSFailure?: boolean;
  failOnThreeDSChallenge?: boolean;
}

External pay button

boolean

Hide in-iframe Pay and Upsell buttons. Call submitPayment() or submitUpsell() from the host page.

boolean

When true, charge as one-time purchase without subscription. Update at runtime via widget.update({ singlePurchase: true }).For Shopify cart checkout, singlePurchase: false alone does not request a subscription. Use shopify.optIn: true and omit singlePurchase or set it to false.

Shopify cart

ShopifyConfig

Shopify-style cart checkout. Totals computed from line items.

{
  showCart?: boolean;       // default true
  disableWallets?: boolean;
  optIn?: boolean;         // true requests subscription opt-in
  cart: [{
    quantity: number;
    variant: number;        // Shopify variant ID
    product: number;        // Shopify product ID
    price: number;
    name: string;
    description?: string;
    imageUrl?: string;
    discountCodeAmount?: number;
  }];
  shipping?: { product: number; name: string; price: number };
}

boolean

default:"false"

On the initial Shopify cart checkout, true requests the subscription configured on the top-level Paysight productId alongside the Shopify order. false or omission processes the order without subscription opt-in. The boolean is forwarded to the API as shopify.optIn.Set it from the customer’s subscription choice before submitting payment. When true, omit the separate top-level singlePurchase flag or set it to false. savePaymentMethod does not request subscription opt-in.See Shopify subscription opt-in for the behavior table and checkout example.

Wallets

boolean

Hide card form when a configured wallet is available; falls back to full UI on error, timeout, or misconfiguration.

boolean

Enable Apple Pay (button renders on host page via applePayContainerId).

object

applePayMerchantId (required), optional style (buttonStyle, buttonType, borderRadius, size).

boolean

Enable Google Pay (host-page container via googlePayContainerId).

object

googlePayMerchantId (required), optional style (buttonStyle, buttonType, borderRadius, size, locale).

Presentation

WidgetTheme

font (Google Fonts URL) and css (class overrides on supported .ps-* classes). See Styling guide.

SupportedLocale

UI locale. Default en-US. See SDK for full list (19 locales).

SupportedCurrency

Display currency. Default USD.

string

In-iframe pay button label.

{ title?: string; description?: string }

Custom success screen copy.

boolean

default:"false"

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

Tracking & attribution

Record<string, string>

String key-value data sent with payment requests. Use campaignName and affiliateName for free-form campaign and affiliate values; campaignId and affiliateId are deprecated internal Paysight identifiers. UTM values, click IDs, landing URLs, and other keys are forwarded as custom metadata. See Tracking & attribution.

Advanced

string

Override default MID routing (account-specific).

API reference — createWidget, update, submitPayment
Events reference
Configuration guide — narrative setup

Widget SDK

Integration Guides

Widget SDK Reference

Examples

Required fields

Customer and fields

3D Secure

Saved payment & upsell

External pay button

Shopify cart

Wallets

Presentation

Tracking & attribution

Advanced

​Required fields

​Customer and fields

​3D Secure

​Saved payment & upsell

​External pay button

​Shopify cart

​Wallets

​Presentation

​Tracking & attribution

​Advanced

​Related

Required fields

Customer and fields

3D Secure

Saved payment & upsell

External pay button

Shopify cart

Wallets

Presentation

Tracking & attribution

Advanced

Related