Integration Modes

Choose how the checkout appears to your customers. Each mode has different trade-offs for user experience and implementation complexity. During checkout, the customer enters their card on our processor’s secure hosted payment page. Checkout currently runs as a full page: in the customer’s current window (redirect), a popup, or a new tab. Iframe embedding is in progress (see Iframe Mode).

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
New Tab	Checkout opens in a new browser tab	Your site stays open in original tab	Simple

Iframe embedding is coming soon. Until it’s available, a session created with embedMode: "iframe" runs as a full-page redirect, and the response includes an EMBED DOWNGRADE message in warnings. To keep customers on your site today, use popup or new tab mode.

Popup and new tab modes are self-serve. Pass parentOrigin in your session create request. 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. parentOrigin is required for popup mode. Set it to the exact origin of the page that opens the popup, for example https://yoursite.com (https://, host, and port if any; no path). Checkout sends its result messages only to that origin, so a mismatch means your page never receives them.

What Happens

Customer clicks “Pay” on your site
A popup window opens with the checkout
In the popup, the customer enters their details and continues to the secure payment page to enter their card
When they finish, checkout sends a postMessage event to your page (PAYMENT_SUCCESS or CHECKOUT_CANCELLED) and closes the popup
Your page updates without a reload

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 Open the popup directly from the customer’s click. Browsers block popups opened any other way (for example after an await or a timer).

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

<script>
// Messages come from the checkout domain you created the session on:
//   production: https://checkout.ozura.com
//   sandbox:    https://sandbox-checkout.ozura.com
const OZURA_ORIGIN = 'https://checkout.ozura.com';
const checkoutUrl = OZURA_ORIGIN + '/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) {
        // Popup blocked: fall back to a full-page redirect
        window.location.href = checkoutUrl;
    }
});

window.addEventListener('message', function(event) {
    if (event.origin !== OZURA_ORIGIN) return; // ignore messages from anywhere else
    
    switch (event.data.type) {
        case 'CHECKOUT_READY':
            console.log('Checkout loaded');
            break;
        case 'PAYMENT_SUCCESS':
            // event.data.paymentData contains transaction details.
            // Confirm the payment on your server before fulfilling the order.
            window.location.href = '/success?transactionId=' + event.data.paymentData.transactionId;
            break;
        case 'CHECKOUT_CANCELLED':
            // Customer cancelled, or left the payment page without completing payment
            console.log('Checkout cancelled');
            break;
        case 'CHECKOUT_EXPIRED':
        case 'CHECKOUT_ERROR':
            console.error('Checkout could not be completed:', event.data.error);
            break;
    }
});
</script>

Keep your successUrl and cancelUrl working. If the popup can’t send its message back (for example the customer closed your original page, or the browser cut the link between the two windows), checkout sends the customer to your successUrl or cancelUrl inside the popup instead.

PAYMENT_SUCCESS is a browser message, not proof of payment. Verify the payment server-side before fulfilling the order.

Iframe Mode (Coming Soon)

Embedding checkout in an iframe on your own page is in progress and not available yet. Until then, if you create a session with embedMode: "iframe", checkout still creates the session but runs it as a full-page redirect. The response tells you so:

{
  "success": true,
  "warnings": [
    "⚠️ EMBED DOWNGRADE: 'iframe' embedding for hosted payments is coming soon but not available yet — this session runs as a full-page 'redirect'. Use 'popup' or 'new_tab' for an embedded hosted-checkout experience. Effective embedMode: redirect."
  ],
  "data": {
    "embedMode": "redirect"
  }
}

The warning describes how checkout behaves today. To keep customers on your site in the meantime, use popup mode or new tab mode.

New Tab Mode

What Happens

A new browser tab opens with the checkout
Your original site stays open in the first tab
The customer completes payment in the new tab
What happens next depends on parentOrigin:
- With parentOrigin: checkout sends the same postMessage events as popup mode to your original tab, then closes the new tab.
- Without parentOrigin: the new tab goes to your successUrl or cancelUrl, and your original tab receives no events.

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

// Open from the customer's click, as with popups
const checkoutUrl = "https://checkout.ozura.com/checkout/session_abc123";
window.open(checkoutUrl, '_blank');

To receive events in your original tab, create the session with parentOrigin and add the same message listener shown in popup mode. Don’t open the tab with noopener: it removes the link checkout uses to send the events back.

PostMessage Events Reference

In popup mode, and new tab mode with parentOrigin, checkout sends these events to your page. They come from the checkout domain you created the session on (https://checkout.ozura.com, or https://sandbox-checkout.ozura.com in sandbox) and are sent only to your parentOrigin.

Event	When It’s Sent	Payload
`CHECKOUT_READY`	The checkout page has loaded	`{ type, sessionId }`
`PAYMENT_SUCCESS`	The payment was approved	`{ type, sessionId, paymentData }`
`CHECKOUT_CANCELLED`	The customer clicked “Cancel and Return”, or came back from the payment page without completing payment	`{ type, sessionId, reason: 'user_cancelled' }`
`CHECKOUT_EXPIRED`	The session expired before the customer paid	`{ type, sessionId, error }`
`CHECKOUT_ERROR`	Checkout hit an error it can’t recover from	`{ type, sessionId, error }`

Declined cards don’t send an event. The customer can retry with another card on the payment page. If they give up and come back, you receive CHECKOUT_CANCELLED.

When the event reaches your page, checkout closes the popup or tab. If it can’t send the event, checkout instead sends the customer to your successUrl (with transaction details as query parameters) or cancelUrl in that window.

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
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 (Coming Soon)

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 (Coming Soon)

​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 (Coming Soon)

New Tab Mode

What Happens

When to Use

Implementation

PostMessage Events Reference

Which Mode Should I Use?