Integration Modes

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

Iframe and popup modes are self-serve. Pass parentOrigin in your session create request and Ozura automatically configures the Content Security Policy for your domain. No registration or approval process is needed.

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.com/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"
  }'

Step 2: Redirect the Customer (BROWSER CODE)

// This runs in the BROWSER (your website's frontend)
window.location.href = checkoutUrl;

No registration needed. Pass parentOrigin: "https://yoursite.com" in your session create request — Ozura uses it to configure Content Security Policy automatically. Your domain is authorized the moment the session is created.

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"
}

Step 2: Open Popup and Listen for Result

<button id="pay-button">Pay $25.00</button>

<script>
const checkoutUrl = "https://checkout.ozura.com/checkout/session_abc123";
let popup = null;

document.getElementById('pay-button').addEventListener('click', function() {
    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.com') return;
    
    switch (event.data.type) {
        case 'CHECKOUT_READY':
            console.log('Checkout loaded');
            break;
        case 'PAYMENT_SUCCESS':
            if (popup) popup.close();
            // event.data.paymentData contains transaction details
            window.location.href = '/success?transactionId=' + event.data.paymentData.transactionId;
            break;
        case 'PAYMENT_ERROR':
            if (popup) popup.close();
            console.error('Payment failed:', event.data.error);
            break;
        case 'CHECKOUT_CANCELLED':
            console.log('Customer cancelled checkout');
            break;
    }
});
</script>

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"
}

Step 2: Embed Iframe

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

<script>
window.addEventListener('message', function(event) {
    if (event.origin !== 'https://checkout.ozura.com') return;
    
    switch (event.data.type) {
        case 'CHECKOUT_READY':
            document.getElementById('checkout-frame').style.display = 'block';
            break;
        case 'PAYMENT_SUCCESS':
            // event.data.paymentData contains transaction details
            window.location.href = '/success?transactionId=' + event.data.paymentData.transactionId;
            break;
        case 'PAYMENT_ERROR':
            console.error('Payment failed:', event.data.error);
            break;
    }
});
</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.com/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	Payload
`CHECKOUT_READY`	Checkout page has fully loaded	`{ type, sessionId }`
`PAYMENT_SUCCESS`	Payment completed successfully	`{ type, sessionId, paymentData }`
`PAYMENT_ERROR`	Payment failed (card declined, processor error, etc.)	`{ type, sessionId, error }`
`CHECKOUT_CANCELLED`	Customer clicked “Cancel and Return”	`{ type, sessionId, reason: 'user_cancelled' }`
`CHECKOUT_ERROR`	An unrecoverable error occurred	`{ type, sessionId, error }`
`CHECKOUT_EXPIRED`	Session was expired	`{ type, sessionId, error }`

In addition to sending PAYMENT_SUCCESS via postMessage, the checkout page also navigates to your successUrl with transaction details as query parameters. For popup and iframe integrations, listen for the PAYMENT_SUCCESS event to update your parent page immediately.

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

Getting Started

Vault

Payments

Integration Modes

Quick Comparison

Redirect Mode (Default)

What Happens

When to Use

Implementation

What Happens

When to Use

Implementation

Iframe Mode

What Happens

When to Use

Implementation

New Tab Mode

What Happens

When to Use

Implementation

PostMessage Events Reference

Which Mode Should I Use?

​Quick Comparison

​Redirect Mode (Default)

​What Happens

​When to Use

​Implementation

​Popup Mode

​What Happens

​When to Use

​Implementation

​Iframe Mode

​What Happens

​When to Use

​Implementation

​New Tab Mode

​What Happens

​When to Use

​Implementation

​PostMessage Events Reference

​Which Mode Should I Use?

Quick Comparison

Redirect Mode (Default)

What Happens

When to Use

Implementation

Popup Mode

What Happens

When to Use

Implementation

Iframe Mode

What Happens

When to Use

Implementation

New Tab Mode

What Happens

When to Use

Implementation

PostMessage Events Reference

Which Mode Should I Use?