Theme Preview

The /preview endpoint renders a fully interactive checkout page backed by a stub session — no database round-trip, no API keys required. It is designed for embedding inside a dashboard theme editor so merchants can see appearance changes in real time.

URL

GET https://checkout.ozura.com/preview              # production
GET https://sandbox-checkout.ozura.com/preview      # sandbox

No authentication headers are required. The page is publicly accessible.

The sandbox preview serves the same stub session and accepts the same postMessage appearance updates as production — it’s purely a visual preview either way. Whichever URL you embed, make sure the postMessage target origin (the second argument to iframe.contentWindow.postMessage) matches that URL exactly. Messages sent with a mismatched target origin are dropped silently.

Embed as an Iframe

<iframe
  id="checkout-preview"
  src="https://checkout.ozura.com/preview"
  style="width: 100%; height: 700px; border: none; border-radius: 12px;"
></iframe>

Sending Appearance Updates

Once the preview iframe loads, send appearance changes via postMessage. The preview page listens for ozura-preview-appearance messages and applies them live using the same applyAppearanceConfig function used by real checkout sessions.

const iframe = document.getElementById('checkout-preview');

function updatePreview(appearance) {
  iframe.contentWindow.postMessage(
    { type: 'ozura-preview-appearance', appearance },
    'https://checkout.ozura.com'
  );
}

// Example: change primary button colour
updatePreview({ primaryColor: '#8b5cf6', borderRadius: 'lg' });

Always specify the target origin ('https://checkout.ozura.com') as the second argument to postMessage. Passing '*' allows any page to intercept the message.

Appearance Message Shape

{
  "type": "ozura-preview-appearance",
  "appearance": {
    "primaryColor": "#8b5cf6",
    "backgroundColor": "#0f0a1a",
    "borderRadius": "lg",
    "fontFamily": "Inter, sans-serif"
  },
  "merchantName": "My Store"
}

Field	Type	Required	Description
`type`	string	Yes	Must be `"ozura-preview-appearance"`
`appearance`	object	No	Any fields from the Appearance Reference. Only the fields you include are updated; others stay at their current values
`merchantName`	string (max 200 chars)	No	Updates the merchant name shown in the checkout header in real time. Omit to leave the current name unchanged

Ready Event

The preview page fires ozura-preview-ready as soon as it mounts. Listen for this event before sending appearance updates to avoid messages being dropped before the listener is registered.

window.addEventListener('message', (event) => {
  if (
    event.origin === 'https://checkout.ozura.com' &&
    event.data?.type === 'ozura-preview-ready'
  ) {
    // Safe to send appearance now
    updatePreview(myCurrentAppearance);
  }
});

Stub Session

The preview runs against a fixed in-memory session:

Field	Value
Amount	`$49.99`
Currency	`USD`
Mode	`payment`
Cart	Single item — “Sample Product”
Merchant name	`"Your Store"`
Status	`pending` (payment form is fully visible)

The Pay button is rendered and interactive but will fail gracefully if clicked — there is no real vault key or payment processor connection. This is intentional: the preview is for visual inspection only.

Limitations

Cannot test actual payments
successUrl, cancelUrl, errorUrl are set to # — no redirect occurs
The session ID is "preview" — it does not exist in the database
Changes made via postMessage are in-memory only and reset on page reload
The preview page ignores messages from opaque origins (null, file://, sandboxed iframes). The parent page must be served over HTTP/HTTPS with a real origin for postMessage to be accepted. The preview pins to the first origin it receives a message from — subsequent messages from a different origin are dropped.

Full Integration Example

<!DOCTYPE html>
<html>
<head>
  <title>Theme Editor</title>
</head>
<body>
  <label>
    Primary Color
    <input type="color" id="primaryColor" value="#9693FE" />
  </label>

  <iframe
    id="checkout-preview"
    src="https://checkout.ozura.com/preview"
    style="width: 480px; height: 700px; border: none;"
  ></iframe>

  <script>
    const iframe = document.getElementById('checkout-preview');
    const primaryColorInput = document.getElementById('primaryColor');

    // Wait for the preview to signal it is ready
    window.addEventListener('message', (event) => {
      if (
        event.origin !== 'https://checkout.ozura.com' ||
        event.data?.type !== 'ozura-preview-ready'
      ) return;

      // Send initial appearance
      sendAppearance();
    });

    primaryColorInput.addEventListener('input', sendAppearance);

    function sendAppearance() {
      iframe.contentWindow.postMessage(
        {
          type: 'ozura-preview-appearance',
          appearance: { primaryColor: primaryColorInput.value }
        },
        'https://checkout.ozura.com'
      );
    }
  </script>
</body>
</html>

Getting Started

Vault

Payments

Theme Preview

URL

Embed as an Iframe

Sending Appearance Updates

Appearance Message Shape

Ready Event

Stub Session

Limitations

Full Integration Example

​URL

​Embed as an Iframe

​Sending Appearance Updates

​Appearance Message Shape

​Ready Event

​Stub Session

​Limitations

​Full Integration Example

URL

Embed as an Iframe

Sending Appearance Updates

Appearance Message Shape

Ready Event

Stub Session

Limitations

Full Integration Example