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.

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 currency units. Ignored when shopify is set (use 0).

'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

Page-2 upsell configuration. Active when both upsellId and initialPaymentSession are set.

{
  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 }).

Shopify cart

ShopifyConfig

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

{
  showCart?: boolean;       // default true
  disableWallets?: boolean;
  optIn?: boolean;
  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 };
}

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