Embedded Checkout

Embedded Checkout is the fastest way to keep payment on your page without building the surrounding form yourself. Paysio renders email, phone, Quick Checkout, saved and new cards, bank accounts when enabled, billing and shipping addresses, eligible Apple Pay and Google Pay buttons, and 3D Secure. Wallet availability follows Settings > Checkout automatically, so there is no session or SDK wallet argument.

The order summary is optional and off by default. Set show_order_summary: true when you want Paysio to render the session's line items, full totals breakdown, recurring charges, and promo-code controls. Leave it off when your site already owns the cart UI.

Contact collection is fully configurable. Set email_field_mode and phone_field_mode independently to editable, read_only, or hidden. Use quick_checkout_behavior to keep detection on typed input, run it when a prefilled email loads, or disable it.

A server-supplied customer_email is authoritative for that Checkout Session. Paysio restores a remembered Quick Checkout session only when it belongs to the same email. A different remembered identity is ignored for this checkout without signing the buyer out elsewhere. Use quick_checkout_behavior: 'on_load' with a read-only or hidden email field when Paysio should check the fixed email automatically.

The two iframe integrations

mountCheckout() creates one outer Paysio iframe for the whole block. Card data inside that checkout still uses processor-secure nested fields such as VGS Collect or Stripe Elements. The merchant page can style and resize the outer checkout, but it never receives card or bank credentials.

Set it up

const response = await fetch('https://paysio.com/api/v1/checkout-sessions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_YOUR_SECRET_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ui_mode: 'embedded',
    allowed_parent_origins: ['https://shop.example.com'],
    show_order_summary: true,
    line_items: [{ product_id: 'product-uuid', quantity: 1 }],
    customer_email: '[email protected]',
    customer_phone: '+15551234567',
    email_field_mode: 'read_only',
    phone_field_mode: 'hidden',
    quick_checkout_behavior: 'on_load',
    appearance: {
      variables: {
        colorPrimary: '#635bff',
        colorBackground: '#ffffff',
        borderRadius: '10px',
        buttonBorderRadius: '999px',
      },
    },
  }),
});

const { data: session } = await response.json();
// Send only session.client_secret to your browser.

<script src="https://paysio.com/paysio.js"></script>
<div id="paysio-checkout"></div>
<script>
  const paysio = Paysio('pk_live_YOUR_PUBLISHABLE_KEY');

  const checkout = await paysio.mountCheckout('#paysio-checkout', {
    clientSecret,
    appearance: {
      variables: {
        colorPrimary: '#635bff',
        colorBackground: '#ffffff',
        colorText: '#18181b',
        colorTextMuted: '#71717a',
        colorBorder: '#d4d4d8',
        borderRadius: '10px',
        buttonBorderRadius: '999px',
        fontFamily: 'Inter, sans-serif',
        fontSize: '16px',
      },
      fonts: [{ cssSrc: 'https://fonts.googleapis.com/css2?family=Inter' }],
    },
    onComplete(result) {
      // Update browser UX only. Confirm payment on your server.
      document.querySelector('#order-number').textContent = result.orderLabel;
    },
    onError(error) {
      console.error(error.message);
    },
  });
</script>

Appearance

Session appearance provides server-defined defaults. The appearance passed to mountCheckout() overrides those defaults.

colorPrimary

Primary button and focus color.

colorBackground

Checkout surface color.

colorText / colorTextMuted

Primary and secondary text colors.

colorBorder

Input and control borders.

borderRadius

Inputs, selectors, and grouped controls.

buttonBorderRadius

Payment button radius.

fontFamily / fontSize

Checkout typography.

fonts[].cssSrc

Up to four HTTPS font stylesheet URLs.

Lifecycle and security

• The iframe resizes itself automatically as checkout content changes.
• Apple Pay and Google Pay appear automatically when enabled in Settings > Checkout and supported by the browser, device, and checkout. Apple Pay also requires HTTPS, a verified parent-page domain, Safari 17 or newer for cross-origin embeds, and a non-recurring live checkout.
• mountCheckout() grants the iframe payment permission automatically. If you render embed_url yourself, add allow="payment *" to that iframe.
• Quick Checkout verification and bank authorization expand over the browser viewport, keep the checkout visible beneath the dimmed overlay, and return to the inline checkout when they close.
• Subscribe with checkout.on('ready' | 'complete' | 'error' | 'resize', callback).
• Change styling after mount with checkout.updateAppearance(appearance); remove the iframe with checkout.unmount().
• Paysio validates the exact parent origin and a per-mount message channel. Never put the client secret in analytics, error reporting, or URLs you create yourself.
• Third-party storage restrictions may prevent automatic Quick Checkout restoration across visits, but email verification and the current checkout continue to work.
• Use payment.completed webhooks or retrieve the Checkout Session on your server before fulfilling an order.