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

# Core concepts

> Checkout modes, sessions, and how the host page talks to the widget

## Architecture

```mermaid theme={null}
flowchart LR
  Host[Host page] -->|createWidget INIT| SDK[Widget SDK]
  SDK -->|iframe| Widget[Payment widget]
  Widget -->|postMessage| SDK
  SDK -->|onMessage subscribe| Host
  Widget --> API[Paysight API]
```

* **Host page** — your site; owns layout, CTAs, and navigation after payment.
* **Widget SDK** — loads the iframe, forwards config, exposes `submitPayment` / `submitUpsell`.
* **Payment widget** — PCI scope; card fields, validation, API calls, 3DS.

## Checkout vs upsell

| Mode         | When                          | Key config                                                       |
| ------------ | ----------------------------- | ---------------------------------------------------------------- |
| **Checkout** | First charge                  | `amount`, card or wallet                                         |
| **Upsell**   | Second charge on another page | `upsell.initialPaymentSession`, `usePreviousPaymentMethod: true` |

Page 1 saves the payment method (`savePaymentMethod: true`) and returns `paysightSession` on `PAYMENT_SUCCESS`. Page 2 passes that value as `upsell.initialPaymentSession` to charge without re-entering card details.

See [Saved payment & upsell](/widget-sdk/guides/saved-payment-and-upsell).

## Session identifiers

| Name              | Who creates it      | Purpose                                                                            |
| ----------------- | ------------------- | ---------------------------------------------------------------------------------- |
| `sessionId`       | **You** (host)      | Idempotency / tracking per checkout attempt in widget config                       |
| `paysightSession` | **Paysight API**    | Returned on successful checkout; required for upsell / saved-method charges        |
| `partnerSession`  | Optional host value | Passed through `data` for your attribution; not a substitute for `paysightSession` |

<Callout type="warning">
  For upsell and `usePreviousPaymentMethod`, always use `paysightSession` from `PAYMENT_SUCCESS.payload` — not your own `sessionId`.
</Callout>

## External pay button

Set `hidePaymentButton: true` to hide the in-iframe Pay/Upsell buttons. Trigger payment from your page with `widget.submitPayment()` or `widget.submitUpsell()`.

See [External payment button](/widget-sdk/guides/external-payment-button).

## Shopify cart mode

When `shopify` is on `WidgetConfig`, line-item totals replace `amount`. Use this for Shopify-style carts and optional upsell on page 2.

See [Shopify cart checkout](/widget-sdk/guides/shopify-cart-checkout).

## Wallets

Apple Pay and Google Pay render in **host-page containers** (`applePayContainerId`, `googlePayContainerId`), not inside the iframe. Optional `showOnlyWalletMethods` hides the card form when a wallet is available.

See [Wallet-only checkout](/widget-sdk/guides/wallet-only-checkout), [Apple Pay](/widget-sdk/guides/apple-pay-via-widget), and [Google Pay](/widget-sdk/guides/google-pay-via-widget).

## 3D Secure

Enable with `threeDSRequired` and related flags on checkout. Upsell can override via `upsell.threeDSRequired`, `upsell.cancelOnThreeDSFailure`, and `upsell.failOnThreeDSChallenge`.

See [3DS via widget](/widget-sdk/guides/3ds-via-widget).

## Updating config at runtime

```javascript theme={null}
widget.update({ singlePurchase: true, amount: 39.99 });
```

Use `update()` for opt-in toggles, amount changes, or refreshing customer data before `submitPayment()`.