> ## 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 reference

> Canonical WidgetConfig fields

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

<Callout type="info">
  `amount` uses **decimal major units** (`29.99`). `productId` is a **number**. When `shopify` is set, pass `amount: 0` — totals are computed from cart lines.
</Callout>

## Required fields

<ParamField path="productId" type="number" required>
  Paysight product ID from your dashboard.
</ParamField>

<ParamField path="sessionId" type="string" required>
  Unique idempotency key per checkout attempt (you generate this).
</ParamField>

<ParamField path="amount" type="number" required>
  Charge amount in decimal currency units. Ignored when `shopify` is set (use `0`).
</ParamField>

<ParamField path="environment" type="'sandbox' | 'production'" required>
  `sandbox` for testing, `production` for live payments.
</ParamField>

## Customer and fields

<ParamField path="customer" type="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) |
</ParamField>

<ParamField path="fields" type="FieldConfig[]">
  **Form layout** — inputs rendered in the iframe. Product requirements determine the minimum set.

  ```typescript theme={null}
  {
    label: string;
    placeholder: string;
    fieldType: 'name' | 'phone' | 'address' | 'city' | 'state' | 'zip' | 'email' | 'country' | 'divider';
    position: 'above' | 'below';  // relative to card form
    size: 'full' | 'half';
  }
  ```
</ParamField>

<ParamField path="disabledCardTypes" type="CardType[]">
  Card brands to hide. Values: `visa`, `mastercard`, `american-express`, `discover`, `diners`, `jcb`, `maestro`, `unionpay`.
</ParamField>

## 3D Secure

<ParamField path="threeDSRequired" type="boolean">
  Require 3DS when supported.
</ParamField>

<ParamField path="cancelOnThreeDSFailure" type="boolean">
  Cancel payment when 3DS fails.
</ParamField>

<ParamField path="failOnThreeDSChallenge" type="boolean">
  Treat 3DS challenge as failure.
</ParamField>

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

## Saved payment & upsell

<ParamField path="savePaymentMethod" type="boolean">
  On checkout, ask the API to store the payment method for a later charge. Works on card, Apple Pay, and Google Pay.
</ParamField>

<ParamField path="usePreviousPaymentMethod" type="boolean">
  Charge using the stored method. Requires `upsell.initialPaymentSession` (the `paysightSession` from page 1).
</ParamField>

<ParamField path="upsell" type="UpsellConfig">
  Page-2 upsell configuration. Active when both `upsellId` and `initialPaymentSession` are set.

  ```typescript theme={null}
  {
    upsellId: string;
    initialPaymentSession: string;  // paysightSession from PAYMENT_SUCCESS
    upsellButton?: { text?: string; style?: StyleObject };
    threeDSRequired?: boolean;
    cancelOnThreeDSFailure?: boolean;
    failOnThreeDSChallenge?: boolean;
  }
  ```
</ParamField>

## External pay button

<ParamField path="hidePaymentButton" type="boolean">
  Hide in-iframe Pay and Upsell buttons. Call `submitPayment()` or `submitUpsell()` from the host page.
</ParamField>

<ParamField path="singlePurchase" type="boolean">
  When `true`, charge as one-time purchase without subscription. Update at runtime via `widget.update({ singlePurchase: true })`.
</ParamField>

## Shopify cart

<ParamField path="shopify" type="ShopifyConfig">
  Shopify-style cart checkout. Totals computed from line items.

  ```typescript theme={null}
  {
    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 };
  }
  ```
</ParamField>

## Wallets

<ParamField path="showOnlyWalletMethods" type="boolean">
  Hide card form when a configured wallet is available; falls back to full UI on error, timeout, or misconfiguration.
</ParamField>

<ParamField path="applePayEnabled" type="boolean">
  Enable Apple Pay (button renders on host page via `applePayContainerId`).
</ParamField>

<ParamField path="applePayOptions" type="object">
  `applePayMerchantId` (required), optional `style` (`buttonStyle`, `buttonType`, `borderRadius`, `size`).
</ParamField>

<ParamField path="googlePayEnabled" type="boolean">
  Enable Google Pay (host-page container via `googlePayContainerId`).
</ParamField>

<ParamField path="googlePayOptions" type="object">
  `googlePayMerchantId` (required), optional `style` (`buttonStyle`, `buttonType`, `borderRadius`, `size`, `locale`).
</ParamField>

## Presentation

<ParamField path="theme" type="WidgetTheme">
  `font` (Google Fonts URL) and `css` (class overrides on supported `.ps-*` classes). See [Styling guide](/widget-sdk/guides/styling).
</ParamField>

<ParamField path="locale" type="SupportedLocale">
  UI locale. Default `en-US`. See SDK for full list (19 locales).
</ParamField>

<ParamField path="currency" type="SupportedCurrency">
  Display currency. Default `USD`.
</ParamField>

<ParamField path="buttonText" type="string">
  In-iframe pay button label.
</ParamField>

<ParamField path="paymentSuccess" type="{ title?: string; description?: string }">
  Custom success screen copy.
</ParamField>

<ParamField path="ecom" type="boolean" default="false">
  Mark the payment as ecommerce. When `true`, sent to the API on card, wallet, and upsell payment paths.
</ParamField>

## Tracking & attribution

<ParamField path="data" type="Record<string, string>">
  Arbitrary key-value pairs sent with payment requests (affiliate IDs, UTM params, landing URL, etc.). See [Tracking & attribution](/widget-sdk/guides/tracking-and-attribution).
</ParamField>

## Advanced

<ParamField path="midOverride" type="string">
  Override default MID routing (account-specific).
</ParamField>

## Related

* [API reference](/widget-sdk/reference/api) — `createWidget`, `update`, `submitPayment`
* [Events reference](/widget-sdk/reference/events)
* [Configuration guide](/widget-sdk/guides/configuration) — narrative setup