Embed Security & Troubleshooting

CSP, origin safety, and production checklist for Checkout Embed SDK

This guide covers secure production setup and common embed issues.

Security Model

The SDK protects modal message handling by validating iframe origin before processing events. Only messages from trusted origins are accepted — forged postMessage events from random origins are ignored.

Trusted origins:

• https://checkout.shoppex.io
• local development origin for checkout app

Because of this, forged postMessage events from random origins are ignored.

---

CSP Setup

If you enforce a Content Security Policy and omit the required frame-src and script-src rules, the checkout iframe will be blocked entirely. Customers will see a blank modal or a browser console error instead of the payment form. Always test your CSP in production, not only locally.

If you run strict CSP, allow checkout iframe + script and pass a nonce to Shoppex.init.

Example policy:

Content-Security-Policy:
  frame-src https://checkout.shoppex.io;
  script-src 'self' 'nonce-YOUR_NONCE' https://checkout.shoppex.io;
  style-src 'self' 'nonce-YOUR_NONCE';

SDK init with nonce:

Shoppex.init({ nonce: 'YOUR_NONCE' });

Why this matters:

• The SDK injects styles into its shadow root.
• The nonce allows those injected styles under strict CSP.

---

Return URL Safety

Never pass unvalidated user input as returnUrl. An attacker could exploit this as an open redirect, sending customers to a phishing page after checkout completes. Always use a hardcoded or server-validated URL.

Use a trusted application URL for returnUrl.

Shoppex.open({
  items: [{ productId: 'PRODUCT_ID' }],
  returnUrl: 'https://app.example.com/checkout/success'
});

Avoid sending unvalidated user input directly as returnUrl.

---

Production Checklist

1. Use HTTPS everywhere

   The embed modal runs inside a cross-origin iframe. Most browsers block mixed content, so your host page must be served over HTTPS.

2. Load the embed script from the correct origin

   Always load from https://checkout.shoppex.io/embed/embed.iife.js — never self-host or proxy the script, as it needs to match the iframe origin.

3. Bind event handlers

   Listen for shoppex:success and shoppex:error events so your app knows when a payment completed or failed. Without these, your UI has no feedback loop.

4. Track conversions

   Fire your analytics conversion event inside the shoppex:success handler. This is the only reliable moment to attribute a sale to your funnel.

5. Validate product and variant IDs

   Double-check that data-shoppex-product-id and data-shoppex-variant-id values match real products. Invalid IDs silently fail to open the modal.

6. Test dark mode and mobile viewports

   The modal adapts to prefers-color-scheme and small screens. Test both to catch layout issues before your customers do.

7. Validate CSP in production

   Your local dev server likely has no CSP. Test your Content Security Policy on the real production domain — CSP violations only surface there.

---

Troubleshooting

Modal does not open

Checklist:

• Script is loaded.
• Element has valid data-shoppex-product-id, data-shoppex-group-id, or data-shoppex-items.
• items contains at least one non-empty productId, unless you pass a valid groupId.
• No JavaScript error before click handler runs.

Wrong product opens

Cause: Multiple items currently resolve to first valid item in modal flow.

Fix: Pass one item per checkout open until multi-item modal support lands.

Event listeners do not fire

Checklist:

• Listen on document, not only on button element.
• Ensure checkout completed successfully for shoppex:success.
• Verify browser extensions/policies are not blocking cross-origin frames.

Modal appears behind custom UI

Use low-risk defaults:

• Avoid custom overlays with extreme z-index values.
• Test with your cookie/privacy banners and support widgets.

Dynamic content buttons do not open checkout

The SDK auto-observes DOM changes, but make sure:

• New nodes actually include data-shoppex-product-id, data-shoppex-group-id, or data-shoppex-checkout.
• Your frontend does not stop propagation on click before SDK handler runs.

---

Debug Helpers

Simple runtime checks:

console.log('Shoppex available:', typeof window.Shoppex !== 'undefined');

document.addEventListener('shoppex:error', (event) => {
  console.error('Embed error:', event.detail.error);
});

---

Related Docs

Embed SDK Overview

Start here for integration patterns.

Embed SDK Reference

Full API, attributes, and event details.

Embed Snippets

Copy-paste code snippets for common embed scenarios.