> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ozura.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Modes

> Choose how the checkout appears to your customers - redirect, popup, iframe, or new tab

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          |

<Note>
  **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.
</Note>

## Redirect Mode (Default)

### What Happens

1. Customer clicks "Pay" on your site
2. Their browser **leaves your website** and goes to the Ozura checkout page
3. 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)**

```bash theme={null}
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)**

```javascript theme={null}
// This runs in the BROWSER (your website's frontend)
window.location.href = checkoutUrl;
```

## Popup Mode

<Note>
  **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.
</Note>

### What Happens

1. Customer clicks "Pay" on your site
2. A small popup window opens with the checkout
3. Customer completes payment in the popup
4. Your site receives a `postMessage` event when payment completes
5. 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"`**

```json theme={null}
{
  "embedMode": "popup",
  "parentOrigin": "https://mystore.com"
}
```

**Step 2: Open Popup and Listen for Result**

```html theme={null}
<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

<Note>
  **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.
</Note>

### What Happens

1. The Ozura checkout form appears **embedded directly in your page**
2. Customer fills out payment info without ever leaving your site
3. 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"`**

```json theme={null}
{
  "embedMode": "iframe",
  "parentOrigin": "https://mystore.com"
}
```

**Step 2: Embed Iframe**

```html theme={null}
<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

1. A **new browser tab** opens with the checkout
2. Your original site stays open in the first tab
3. After payment, the new tab redirects to your `successUrl`
4. 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

```javascript theme={null}
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 }`                    |

<Note>
  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.
</Note>

## 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 |