External button checkout & upsell

Use hidePaymentButton: true with host-rendered buttons for a funnel-style checkout and upsell experience.

Live demo

Open the interactive external-button demo in the sandbox playground.

Current limitation: identifying upsell transactionsWidget upsells do not currently have a per-offer product name or label in the Paysight transaction view, and upsellId is not displayed there.The initial payment and each upsell appear as separate transaction entries. Both are labelled SINGLE PURCHASE, unless the customer opts into a subscription on the initial payment, which is labelled OPT IN. These labels do not identify the upsell or its position in the chain.For now, compare transaction amounts with your configured checkout and upsell prices to identify the initial payment and upsells 1, 2, 3, and so on. Offers with the same price cannot be reliably distinguished by amount alone.We are working on adding upsell labels/product names, but they are not available yet.

Before you start

Use one Paysight productId for the initial payment and every upsell in the journey.
Set savePaymentMethod: true on the initial checkout. Save the paysightSession from its successful PAYMENT_SUCCESS event.
For every upsell, reuse that original session as upsell.initialPaymentSession, set usePreviousPaymentMethod: true, and supply the upsell’s own amount.
Give each offer a unique, stable upsellId, such as upsell-1 or upsell-product-name. Keep the same ID when retrying the same offer.
Call submitPayment() for checkout and submitUpsell() when the customer accepts an upsell. Creating a widget does not charge the customer.

Initial payment amount

amount is required and uses decimal major units of your configured currency.

Value	What the customer is charged
`amount: 0`	The immediate charge configured on the subscription attached to the Paysight product, when set.
`amount > 0`	The supplied amount, overriding the subscription’s immediate charge.

amount: 0 does not mean a free payment. The examples use amount: 29.99 to override the immediate charge and amount: 9.99 for the upsell. Shopify cart mode is different: cart totals determine the amount.

Page 1 — checkout with external button

<div id="widget"></div>

<label>
  <input type="checkbox" id="single-purchase" />
  One-time purchase only (no subscription)
</label>

<button id="pay-btn" type="button" disabled>Pay $29.99</button>

<script src="https://payment.paysight.io/widget-sdk.js"></script>
<script>
  const widget = PaySightSDK.createWidget({
    targetId: 'widget',
    config: {
      productId: YOUR_PRODUCT_ID, // Same Paysight product ID on both pages
      sessionId: 'checkout-' + Date.now(),
      environment: 'sandbox',
      amount: 29.99, // Overrides the subscription immediate charge; use 0 to use it
      hidePaymentButton: true,
      savePaymentMethod: true,
      customer: { email: 'customer@example.com', country: 'US' },
    },
    onMessage: (msg) => {
      if (msg.type === 'READY') {
        document.getElementById('pay-btn').disabled = false;
      }
      if (msg.type === 'PAYMENT_SUCCESS') {
        const session = msg.payload?.paysightSession;
        if (session) {
          sessionStorage.setItem('paysightSession', session);
          window.location.href = '/upsell';
        }
      }
      if (msg.type === 'ERROR') {
        console.warn(msg.payload.code, msg.payload.message);
      }
    },
  });

  document.getElementById('single-purchase').onchange = (e) => {
    widget.update({ singlePurchase: e.target.checked });
  };

  document.getElementById('pay-btn').onclick = () => widget.submitPayment();
</script>

Page 2 — upsell with external button

<div id="upsell-widget"></div>
<button id="upsell-btn" type="button" disabled>Add warranty — $9.99</button>

<script src="https://payment.paysight.io/widget-sdk.js"></script>
<script>
  const widget = PaySightSDK.createWidget({
    targetId: 'upsell-widget',
    config: {
      productId: YOUR_PRODUCT_ID, // Same Paysight product ID on both pages
      sessionId: 'upsell-' + Date.now(),
      environment: 'sandbox',
      amount: 9.99, // This accepted upsell's charge amount
      hidePaymentButton: true,
      usePreviousPaymentMethod: true,
      upsell: {
        upsellId: 'upsell-warranty', // Unique per offer; stable for retries
        initialPaymentSession: sessionStorage.getItem('paysightSession'),
        threeDSRequired: true,
      },
      customer: { email: 'customer@example.com' },
    },
    onMessage: (msg) => {
      if (msg.type === 'READY') {
        document.getElementById('upsell-btn').disabled = false;
      }
      if (
        (msg.type === 'PAYMENT_SUCCESS' && msg.payload?.mode === 'upsell') ||
        msg.type === 'DUPLICATE_TRANSACTION'
      ) {
        window.location.href = '/thank-you';
      }
    },
  });

  document.getElementById('upsell-btn').onclick = () => widget.submitUpsell();
</script>

Error codes to handle

Code	Action
`NOT_READY`	Keep pay button disabled until `READY`
`VALIDATION_FAILED`	Show `missingFields` to user
`INVALID_MODE`	Use `submitUpsell` on page 2, not `submitPayment`
`PAYMENT_IN_PROGRESS`	Disable button during processing

See Error codes.

Additional upsells and offer identification

For a second or later upsell, create another widget with the same Paysight productId and the original initial payment’s paysightSession. Set a different upsellId and that offer’s amount, then call submitUpsell() after acceptance. data.campaignName and data.affiliateName are forwarded, but established attribution is reused for the shared product/session. Changing these names does not reliably identify each purchased offer. upsellId appears in widget events and duplicate detection, but is not returned by the current transaction list/detail APIs. Keep the offer ID with the payment result in your own order records.

Widget SDK

Integration Guides

Widget SDK Reference

Examples

Live demo

Before you start

Initial payment amount

Page 1 — checkout with external button

Page 2 — upsell with external button

Error codes to handle

Additional upsells and offer identification

Live demo

​Before you start

​Initial payment amount

​Page 1 — checkout with external button

​Page 2 — upsell with external button

​Error codes to handle

​Additional upsells and offer identification

​Related

Before you start

Initial payment amount

Page 1 — checkout with external button

Page 2 — upsell with external button

Error codes to handle

Additional upsells and offer identification

Related