Choose how the checkout appears to your customers. Each mode has different trade-offs for user experience and implementation complexity.
Quick Comparison
| Mode | What Happens | Customer Experience | Code Complexity |
|---|
| Redirect | Browser navigates away to checkout | Leaves your site, returns after payment | Simplest |
| Popup | Checkout opens in a small popup window | Stays on your site, popup in front | Medium |
| Iframe | Checkout embedded directly in your page | Never leaves your site | Medium |
| New Tab | Checkout opens in a new browser tab | Your site stays open in original tab | Simple |
Domain registration: Popup and iframe modes require your domain to be registered with Ozura. Redirect and new tab modes work without registration.
Redirect Mode (Default)
What Happens
- Customer clicks “Pay” on your site
- Their browser leaves your website and goes to the Ozura checkout page
- After payment, they’re redirected back to your
successUrl, cancelUrl, or errorUrl
When to Use
- Mobile apps (popups often blocked on mobile)
- Simple websites without JavaScript
- Email payment links
- When you want the simplest possible integration
Implementation
Step 1: Create Session (SERVER CODE)
curl -X POST https://checkout.ozura.io/api/sessions/create \
-H "Content-Type: application/json" \
-H "X-API-KEY: your_vault_api_key" \
-H "X-OZURA-API-KEY: your_merchant_api_key" \
-d '{
"merchantId": "your_merchant_id",
"merchantName": "My Store",
"amount": "25.00",
"currency": "USD",
"successUrl": "https://mystore.com/success",
"cancelUrl": "https://mystore.com/cancel",
"errorUrl": "https://mystore.com/error"
}'
// This runs in the BROWSER (your website's frontend)
window.location.href = checkoutUrl;
Prerequisite: Your domain must be registered with Ozura before using popup mode.
What Happens
- Customer clicks “Pay” on your site
- A small popup window opens with the checkout
- Customer completes payment in the popup
- Your site receives a
postMessage event when payment completes
- You close the popup and update your page
When to Use
- Desktop websites where you want customers to stay on your page
- Single-page applications (SPAs)
- When you want to update your page without a full reload
Implementation
Step 1: Create Session with embedMode: "popup"
{
"embedMode": "popup",
"parentOrigin": "https://mystore.com"
}
<button id="pay-button">Pay $25.00</button>
<script>
const checkoutUrl = "https://checkout.ozura.io/checkout/session_abc123";
document.getElementById('pay-button').addEventListener('click', function() {
const popup = window.open(
checkoutUrl,
'OzuraCheckout',
'width=500,height=700,scrollbars=yes,resizable=yes'
);
if (!popup || popup.closed) {
alert('Popup blocked! Please allow popups for this site.');
return;
}
});
window.addEventListener('message', function(event) {
if (event.origin !== 'https://checkout.ozura.io') return;
switch (event.data.type) {
case 'CHECKOUT_READY':
console.log('Checkout loaded');
break;
case 'CHECKOUT_CANCELLED':
console.log('Customer cancelled checkout');
break;
}
});
</script>
Iframe Mode
Prerequisite: Your domain must be registered with Ozura before using iframe mode.
What Happens
- The Ozura checkout form appears embedded directly in your page
- Customer fills out payment info without ever leaving your site
- Your page receives a
postMessage event when payment completes
When to Use
- When you want checkout to feel like part of your site
- Checkout pages where you show order summary alongside payment form
- Single-page applications (SPAs)
Implementation
Step 1: Create Session with embedMode: "iframe"
{
"embedMode": "iframe",
"parentOrigin": "https://mystore.com"
}
<iframe
id="checkout-frame"
src="https://checkout.ozura.io/checkout/session_abc123"
style="width: 100%; height: 700px; border: none;">
</iframe>
<script>
window.addEventListener('message', function(event) {
if (event.origin !== 'https://checkout.ozura.io') return;
if (event.data.type === 'CHECKOUT_READY') {
document.getElementById('checkout-frame').style.display = 'block';
}
});
</script>
New Tab Mode
What Happens
- A new browser tab opens with the checkout
- Your original site stays open in the first tab
- After payment, the new tab redirects to your
successUrl
- If customer cancels, the tab closes automatically
When to Use
- When popups are blocked (some browsers block popups but allow new tabs)
- When you want your site to stay open while customer pays
Implementation
const checkoutUrl = "https://checkout.ozura.io/checkout/session_abc123";
window.open(checkoutUrl, '_blank');
PostMessage Events Reference
For popup, iframe, and new_tab modes, the checkout sends these events to your page:
| Event | When It’s Sent |
|---|
CHECKOUT_READY | Checkout page has fully loaded |
CHECKOUT_CANCELLED | Customer clicked “Cancel and Return” |
CHECKOUT_ERROR | An unrecoverable error occurred |
CHECKOUT_EXPIRED | Session was expired |
Payment success does NOT send a postMessage. When the customer pays successfully, the checkout page navigates to your successUrl. If you need your parent page to react, your successUrl page should call window.opener.postMessage(...) back to the parent.
Which Mode Should I Use?
| If you want… | Use | Why |
|---|
| Simplest possible integration | Redirect | No JavaScript needed |
| Customer to stay on your site (desktop) | Popup | Your page stays visible |
| Checkout to feel built into your page | Iframe | Seamless experience |
| Avoid popup blockers | New Tab | Less likely to be blocked |
| Mobile-friendly | Redirect | Popups often blocked on mobile |
