Iframe Integration

Embed PayOrc's checkout directly into your website using an iframe. Supports full embed and popup modal modes with responsive design and security best practices.

Iframe Integration

Version: 3.0.0

What is Iframe Integration? Iframe integration lets you embed PayOrc's secure checkout directly inside your own website. Instead of redirecting the customer away, the payment form loads inside a sandboxed frame — keeping your brand front and center throughout the entire payment experience.

Prerequisites

An active PayOrc merchant account
An API key generated for the Hosted Solution channel
- Navigate to Developers → API Keys → Add new API key → Select "Hosted Solution" in the Channel dropdown
An order already created via the Hosted Payment Page API — you need the iframe_link from the response

Method	Best For	Pros	Cons
Embed	Dedicated checkout pages	Always visible, seamless UX, no extra clicks	Takes up page real estate
Popup	Multi-step flows, product pages	Minimal page disruption, focused attention	Requires JS to trigger, popup blockers possible

Use Embed when: You have a dedicated checkout or payment page and want the form always visible.

Use Popup when: You're on a product page or cart and want to show the checkout only when the user clicks "Pay Now."

Step 1: Get the iframe_link

When you create an order via the API, the response includes both payment_link and iframe_link. Use the iframe_link for embedding.

{
    "status": "SUCCESS",
    "status_code": 00,
    "message": "Order created",
    "p_order_id": 1000010240,
    "m_order_id": "CUST-10042",
    "payment_link": "https://checkout.payorc.com/pay/abc123xyz",
    "iframe_link": "https://checkout.payorc.com/embed/abc123xyz"
}

Method 1: Embed (Inline Iframe)

The embed method places the checkout directly in a container on your page. The customer sees the full payment form without any redirects.

Basic Embed

Create-order body matches Payment Request API. All required objects must be present. Use the returned iframe_link in your HTML.

# Fetch iframe_link via create order, then embed it in HTML

curl --location 'https://api.payorc.com/orders/v1/create' \
--header 'merchant-key: YOUR_MERCHANT_KEY' \
--header 'merchant-secret: YOUR_MERCHANT_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": {
        "class": "ECOM",
        "action": "AUTH",
        "capture_method": "AUTOMATIC",
        "payment_token": "",
        "customer_details": {
            "m_customer_id": "",
            "name": "John Doe",
            "email": "[email protected]",
            "mobile": "9876543210",
            "code": "91"
        },
        "order_details": {
            "m_order_id": "ORDER-12345",
            "amount": 100,
            "quantity": 1,
            "convenience_fee": 0,
            "currency": "AED",
            "description": "Order #12345",
            "return_url": ""
        },
        "billing_details": {
            "address_line1": "123 Main Street",
            "address_line2": "",
            "city": "Dubai",
            "province": "Dubai",
            "country": "AE",
            "pin": "54044"
        },
        "shipping_details": {
            "shipping_name": "John Doe",
            "shipping_email": "[email protected]",
            "shipping_code": "",
            "shipping_mobile": "",
            "address_line1": "123 Main Street",
            "address_line2": "",
            "city": "Dubai",
            "province": "Dubai",
            "country": "AE",
            "pin": "54044",
            "location_pin": "",
            "shipping_currency": "AED",
            "shipping_amount": 0
        },
        "urls": {
            "success": "https://your-site.com/success",
            "cancel": "https://your-site.com/cancel",
            "failure": "https://your-site.com/failure",
            "webhook_url": "https://your-site.com/webhook"
        },
        "parameters": [
            {
                "alpha": ""
            },
            {
                "beta": ""
            },
            {
                "gamma": ""
            },
            {
                "delta": ""
            },
            {
                "epsilon": ""
            }
        ],
        "custom_data": [
            {
                "alpha": ""
            },
            {
                "beta": ""
            },
            {
                "gamma": ""
            },
            {
                "delta": ""
            },
            {
                "epsilon": ""
            }
        ],
        "items": [
            {
                "title": "Premium Plan",
                "description": "Monthly subscription",
                "quantity": 1,
                "unit_price": "100.00",
                "discount_amount": "0.00",
                "reference_id": "SKU-001",
                "image_url": "",
                "product_url": "",
                "gender": "",
                "category": "Subscription",
                "color": "",
                "product_material": "",
                "size_type": "",
                "size": "",
                "brand": "PayOrc",
                "is_refundable": true
            }
        ]
    }
}'
# Use the returned iframe_link in your HTML below

HTML Structure

<div class="checkout-wrapper">
    <h2>Complete Your Payment</h2>
    <div class="checkout-container">
        <iframe
            src="https://checkout.payorc.com/embed/YOUR_IFRAME_TOKEN"
            class="payorc-checkout"
            frameborder="0"
            scrolling="no"
            allow="payment"
            title="PayOrc Secure Checkout"
        ></iframe>
    </div>
</div>

Responsive CSS

The iframe must be responsive to work on all screen sizes. Use this CSS to ensure the checkout scales correctly:

# CSS is not sent via cURL — this is for reference in your stylesheet.
# Add this to your project's CSS file.

The popup method opens the checkout inside a modal overlay. The customer stays on your page and sees the payment form in a centered popup.

# The popup is a frontend-only feature. Use cURL to create the order first,
# then embed the modal HTML in your checkout page.

curl --location 'https://api.payorc.com/orders/v1/create' \
--header 'merchant-key: YOUR_MERCHANT_KEY' \
--header 'merchant-secret: YOUR_MERCHANT_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": {
        "class": "ECOM",
        "action": "AUTH",
        "capture_method": "AUTOMATIC",
        "payment_token": "",
        "customer_details": {
            "m_customer_id": "",
            "name": "Jane Smith",
            "email": "[email protected]",
            "mobile": "5551234567",
            "code": "1"
        },
        "order_details": {
            "m_order_id": "ORDER-POPUP-001",
            "amount": 250,
            "quantity": 1,
            "convenience_fee": 0,
            "currency": "USD",
            "description": "Product purchase",
            "return_url": ""
        },
        "billing_details": {
            "address_line1": "123 Main Street",
            "address_line2": "",
            "city": "Dubai",
            "province": "Dubai",
            "country": "AE",
            "pin": "54044"
        },
        "shipping_details": {
            "shipping_name": "Jane Smith",
            "shipping_email": "[email protected]",
            "shipping_code": "",
            "shipping_mobile": "",
            "address_line1": "123 Main Street",
            "address_line2": "",
            "city": "Dubai",
            "province": "Dubai",
            "country": "AE",
            "pin": "54044",
            "location_pin": "",
            "shipping_currency": "USD",
            "shipping_amount": 0
        },
        "urls": {
            "success": "https://your-site.com/success",
            "cancel": "https://your-site.com/cancel",
            "failure": "https://your-site.com/failure",
            "webhook_url": "https://your-site.com/webhook"
        },
        "parameters": [
            {
                "alpha": ""
            },
            {
                "beta": ""
            },
            {
                "gamma": ""
            },
            {
                "delta": ""
            },
            {
                "epsilon": ""
            }
        ],
        "custom_data": [
            {
                "alpha": ""
            },
            {
                "beta": ""
            },
            {
                "gamma": ""
            },
            {
                "delta": ""
            },
            {
                "epsilon": ""
            }
        ],
        "items": [
            {
                "title": "Premium Plan",
                "description": "Monthly subscription",
                "quantity": 1,
                "unit_price": "100.00",
                "discount_amount": "0.00",
                "reference_id": "SKU-001",
                "image_url": "",
                "product_url": "",
                "gender": "",
                "category": "Subscription",
                "color": "",
                "product_material": "",
                "size_type": "",
                "size": "",
                "brand": "PayOrc",
                "is_refundable": true
            }
        ]
    }
}'
# Use iframe_link in the modal src below

# Reference CSS for the modal — add to your stylesheet

Security Best Practices

Critical Security Rules for Iframe Integration

Never expose API keys in client-side code. Always create the order on your server and pass the iframe_link to the frontend. The examples above follow this pattern.
Validate the iframe origin. When listening for postMessage events, always check event.origin matches https://checkout.payorc.com. Ignore messages from unknown origins.

Use sandbox attribute for restricted iframes (optional but recommended):

<iframe
    src="https://checkout.payorc.com/embed/TOKEN"
    sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
    class="payorc-checkout"
    frameborder="0"
></iframe>

Set Content-Security-Policy headers on your page to restrict iframe sources:
```
Content-Security-Policy: frame-src https://checkout.payorc.com;
```
Always use HTTPS. PayOrc checkout pages are served over HTTPS. Your page must also be served over HTTPS to avoid mixed-content warnings.
Do not modify the iframe URL. Always use the exact iframe_link returned by the API. Never append parameters or alter the URL.

Responsive Design

The PayOrc checkout iframe is designed to be responsive, but you should still handle edge cases:

Minimum width: The checkout form works best at 320px and above.
Height: Start with min-height: 600px for desktop and min-height: 800px for mobile.
Dynamic height: Use postMessage to receive real-time height updates from the iframe as the customer progresses through the checkout steps.
Mobile: On small screens, consider using the popup modal instead of embed to maximize the payment form visibility.

# Responsive CSS reference — add to your stylesheet

Troubleshooting

Issue	Cause	Solution
Blank iframe	API key not generated for Hosted Solution channel	Create API key with "Hosted Solution" channel in Developers → API Keys
Mixed content warning	Page served over HTTP	Ensure your page is served over HTTPS
iframe not resizing	postMessage origin mismatch	Verify `event.origin` matches `https://checkout.payorc.com`
Popup blocked	Browser blocked the popup	Use `window.open` after a user-initiated click, or use the embed method instead
Checkout expired	Payment link older than 15 minutes	Create a new order and use the fresh `iframe_link`

Iframe Integration

On this page