---
title: iFrame Checkout Integration Steps
slug: iframe-checkout/integration-steps
excerpt: >-
  Step-by-step guide to embed Pine Labs checkout inside an iFrame on your page.
  Authenticate, generate a checkout link, embed the iFrame, and handle payment
  callbacks.
hidden: false
sidebar_order: 3
metadata:
  title: Integration Steps for Iframe Checkout – Pine Labs Payment Gateway
  description: >-
    Step-by-step guide to embed Pine Labs checkout inside an iFrame on your
    page. Authenticate, generate a checkout link, embed the iFrame, and handle
    payment callbacks.
  robots: index
---
Embed the Pine Labs checkout experience inside an iFrame on your page.

The iFrame integration uses the same API as Hosted checkout — [Generate Checkout Link](/api/checkout/generate-checkout-link) — with `integration_mode` set to `IFRAME`. The steps are identical to the Hosted checkout integration. The only difference is how you display the checkout to the customer.

1. [Prerequisite] Generate Token
2. Generate Checkout Link (with `integration_mode: IFRAME`)
3. Embed the checkout URL in an iFrame
4. Handle Payment
   - Detect callback in the iFrame
   - Verify Payment Signature

---

## Before you begin

- Sign up for a [Pine Labs account](https://dashboardv2.pluralonline.com/signup) and retrieve your `client_id` and `client_secret`
- Store credentials securely on your backend
- All API calls must be from your backend server
- Use TLS 1.2 or higher

| Environment | Base URL |
|---|---|
| **UAT (Sandbox)** | `https://pluraluat.v2.pinepg.in` |
| **Production** | `https://api.pluralonline.com` |

---

## Step 1. Generate Token

Authenticate with Pine Labs to get an access token.

**Endpoint:** `POST /api/auth/v1/token`

```bash
curl --request POST \
  --url https://pluraluat.v2.pinepg.in/api/auth/v1/token \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
  --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
  --data '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "grant_type": "client_credentials"
  }'
```

See [Generate Token API reference](/api/authentication/generate-token).

---

## Step 2. Generate Checkout Link

Create an order and get the checkout URL. Set `integration_mode` to `IFRAME`.

**Endpoint:** `POST /api/checkout/v1/orders`

```bash
curl --request POST \
  --url https://pluraluat.v2.pinepg.in/api/checkout/v1/orders \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
  --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
  --header 'accept: application/json' \
  --data '{
    "merchant_order_reference": "112345",
    "order_amount": {
      "value": 1100,
      "currency": "INR"
    },
    "integration_mode": "IFRAME",
    "pre_auth": false,
    "allowed_payment_methods": [
      "CARD", "UPI", "NETBANKING", "WALLET"
    ],
    "callback_url": "https://yoursite.com/payment/success",
    "failure_callback_url": "https://yoursite.com/payment/failure",
    "purchase_details": {
      "customer": {
        "email_id": "kevin.bob@example.com",
        "first_name": "Kevin",
        "last_name": "Bob",
        "mobile_number": "9876543210",
        "country_code": "91"
      }
    }
  }'
```

The response includes a `redirect_url`. Use this as the iFrame `src`.

See [Generate Checkout Link API reference](/api/checkout-and-links/create-payment-link).

---

## Step 3. Embed the iFrame

Add the iFrame to your page using the `redirect_url` from Step 2.

### Basic embedding

```html
<iframe
  id="pinelabs-checkout"
  src="{redirect_url}"
  width="100%"
  height="700"
  frameborder="0"
  allow="payment"
  style="border: none;"
></iframe>
```

### Responsive embedding

```html
<div class="checkout-container" style="max-width: 600px; margin: 0 auto;">
  <iframe
    id="pinelabs-checkout"
    src="{redirect_url}"
    width="100%"
    height="700"
    frameborder="0"
    allow="payment"
    style="border: none; min-height: 600px;"
  ></iframe>
</div>
```

### Dynamic iFrame creation (JavaScript)

```javascript
function loadCheckout(redirectUrl) {
  const container = document.getElementById('checkout-container');
  const iframe = document.createElement('iframe');
  iframe.id = 'pinelabs-checkout';
  iframe.src = redirectUrl;
  iframe.width = '100%';
  iframe.height = '700';
  iframe.frameBorder = '0';
  iframe.allow = 'payment';
  iframe.style.border = 'none';
  container.appendChild(iframe);
}
```

---

## Step 4. Handle Payment

After payment, Pine Labs redirects to your `callback_url` inside the iFrame. You need to detect this redirect and handle it on the parent page.

### 4.1 Detect callback in the iFrame

Since the callback redirect happens inside the iFrame, use one of these approaches to update the parent page:

**Option A: Server-side callback page with parent redirect**

Create a callback page that redirects the parent window:

```html
<!-- callback.html (served at your callback_url) -->
<script>
  // Extract parameters from the URL
  const params = new URLSearchParams(window.location.search);
  const orderId = params.get('order_id');
  const status = params.get('status');

  // Redirect parent page
  if (window.parent !== window) {
    window.parent.location.href = '/order-confirmation?order_id=' + orderId + '&status=' + status;
  }
</script>
```

**Option B: Use window.postMessage**

```html
<!-- callback.html -->
<script>
  const params = new URLSearchParams(window.location.search);
  const data = {
    type: 'PINELABS_PAYMENT',
    order_id: params.get('order_id'),
    status: params.get('status'),
    signature: params.get('signature')
  };
  window.parent.postMessage(data, 'https://yoursite.com');
</script>
```

Listen on the parent page:

```javascript
window.addEventListener('message', function(event) {
  if (event.origin !== 'https://yoursite.com') return;
  if (event.data.type === 'PINELABS_PAYMENT') {
    // Handle payment result
    console.log('Order:', event.data.order_id);
    console.log('Status:', event.data.status);
    // Remove iFrame and show confirmation
    document.getElementById('pinelabs-checkout').remove();
    showOrderConfirmation(event.data);
  }
});
```

### 4.2 Verify payment signature

**This step is mandatory.** Verify the SHA256 HMAC signature server-side.

1. Build a request string from callback parameters, sorted alphabetically by key, joined with `&`
2. Generate SHA256 HMAC using your `secret_key`
3. Compare with the `signature` from the callback

See [Hosted checkout — Integration steps](/docs/checkout-hosted-integration) for the full signature verification implementation.

### 4.3 Check order status

Use [Get Order by Order ID](/api/orders/get-order) to confirm the payment status server-side.

```bash
GET /api/pay/v1/orders/{order_id}
```

---

## Post-integration: Manage transactions

### Capture order (pre-auth only)

If `pre_auth: true`, capture the payment after verification:

```bash
PUT /api/pay/v1/orders/{order_id}/capture
```

See [Capture Order API](/api/orders/capture-order).

### Cancel order

```bash
PUT /api/pay/v1/orders/{order_id}/cancel
```

See [Cancel Order API](/api/orders/cancel-order).

### Webhooks

Configure [webhooks](/developer-tools/webhooks) for reliable server-to-server notifications.

---

## Test your integration

| Test scenario | Details |
|---|---|
| **Cards** | Use [test card details](/docs/payments-test-card-details) in UAT |
| **Net Banking** | Test via SBI in UAT |
| **UPI** | Processes real transactions — use minimum amount |
| **iFrame rendering** | Test on Chrome, Firefox, Safari, Edge, and mobile browsers |
| **Responsive layout** | Test on multiple screen sizes |

> Production credentials are shared after UAT sign-off.

---

## Related pages

> **[iFrame checkout — Overview](/docs/checkout-iframe)**
> Features and benefits of iFrame checkout.

> **[iFrame checkout — Customization options](/docs/checkout-iframe-customization)**
> Configure iFrame dimensions, payment methods, and branding.

> **[Hosted checkout — Integration steps](/docs/checkout-hosted-integration)**
> Same API flow — reference for signature verification and callback handling.

> **[Generate Checkout Link API reference](/api/checkout-and-links/create-payment-link)**
> Full API documentation.