Skip to main content
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:
SDK init with 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.
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

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

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.