Skip to main content

​
Architecture

  • 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

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.

​
Session identifiers

For upsell and usePreviousPaymentMethod, always use paysightSession from PAYMENT_SUCCESS.payload — not your own sessionId.

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

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

​
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, Apple Pay, and Google Pay.

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

​
Updating config at runtime

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