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

# iFrame Integration

> Embed the PayGlocal Verification Suite — VKYC, DigiLocker, and T&C acknowledgement — directly inside your partner dashboard.

Partners can embed the PayGlocal Verification Suite directly into their existing dashboard so merchants can complete identity verification without leaving the partner platform.

The verification suite covers:

* **VKYC** — Video-based KYC using the merchant's live camera
* **DigiLocker** — Government document verification via DigiLocker
* **T\&C Acknowledgement** — Merchant accepts PayGlocal terms and conditions

***

## Step 1: Domain Whitelisting (Action Required)

<Warning>
  Your iFrame **will not render** until your domain is whitelisted by PayGlocal. This step must be completed before testing the iFrame in any environment.
</Warning>

PayGlocal uses a strict **Content Security Policy (CSP)** with `frame-ancestors` directives to prevent Clickjacking attacks. Browsers will display a `frame-ancestors violation` console error and block the iFrame until your domain is authorized.

**To request whitelisting**, contact your assigned PayGlocal Account Manager with:

| Field            | Value                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------- |
| **Partner Name** | Your legal entity name                                                                  |
| **Environment**  | Sandbox, Production, or both                                                            |
| **Domain URLs**  | Exact URLs where the iFrame will be hosted (e.g., `https://onboarding.yourcompany.com`) |

Allow 1–2 business days for the PayGlocal team to activate the CSP allowance.

***

## Step 2: Integration Workflow

<Steps>
  <Step title="Initialize — Generate the verification session URL">
    Before rendering the iFrame, call the [Get Verification Redirect API](/api-reference/get-verification-redirect) from your **backend** to generate a session URL for the merchant.

    ```bash theme={null}
    BODY='{"callBackUrl":"https://your-domain.com/onboarding-success"}'
    DIGEST=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

    curl -X PUT "https://api.onboard.uat.payglocal.in/gcc/v2/partner/merchant/verification/{onboardingId}/redirect" \
      -H "Content-Type: application/json" \
      -H "x-gl-auth: $API_KEY" \
      -H "x-gl-digest: $DIGEST" \
      -d "$BODY"
    ```

    Response:

    ```json theme={null}
    {
      "gid": "gl_9c2645ed09edb22e",
      "timestamp": "10/01/2026 15:00:00",
      "reasonCode": "",
      "message": "digilocker redirect url generated successfully",
      "data": {
        "redirectLink": "https://uat.dashboard.payglocal.in/app/partner-onboarding?token=abc123&onboardingId=pg_onboard_abc123",
        "onboardingId": "pg_onboard_abc123"
      }
    }
    ```

    Save the `data.redirectLink` value — this is the `src` for your iFrame. The URL includes a single-use session token valid for 24 hours.

    <Note>
      The `callBackUrl` is stored on the merchant record and used as the redirect target after verification completes. It must be a full HTTPS URL on your whitelisted domain.
    </Note>
  </Step>

  <Step title="Embed — Load the redirectLink in an iFrame">
    Inject the `redirectLink` as the `src` of an iFrame on your page. The `allow` attributes below are **mandatory** — without them, the browser will block camera and microphone access during VKYC.

    ```html theme={null}
    <div id="pg-iframe-wrapper" style="width: 100%; max-width: 1000px; height: 800px; margin: auto;">
      <iframe
        id="payglocal-onboarding-ui"
        src="INSERT_REDIRECT_LINK_HERE"
        width="100%"
        height="700px"
        allow="camera; microphone; geolocation"
        frameborder="0"
        style="border: 1px solid #e0e0e0; border-radius: 8px;">
      </iframe>
    </div>
    ```

    ```javascript theme={null}
    // Dynamically set the src after fetching the redirectLink from your backend
    const iframe = document.getElementById("payglocal-onboarding-ui");
    iframe.src = redirectLink; // value returned by the Get Verification Redirect API
    ```
  </Step>

  <Step title="Handle Callback — Listen for completion">
    PayGlocal signals completion in two ways:

    **Option A — postMessage (recommended for real-time UX)**

    Listen for `message` events from the iFrame. When verification completes, PayGlocal posts `PARTNER_MERCHANT_VERIFICATION_COMPLETE`.

    ```javascript theme={null}
    window.addEventListener("message", function(event) {
      // Validate origin — UAT or Production dashboard domain
      const allowedOrigins = [
        "https://uat.dashboard.payglocal.in",
        "https://dashboard.payglocal.in"
      ];
      if (!allowedOrigins.includes(event.origin)) return;

      if (event.data === "PARTNER_MERCHANT_VERIFICATION_COMPLETE") {
        console.log("Merchant verification completed.");
        // Trigger server-side GET /status to confirm final state
      }
    }, false);
    ```

    During intermediate steps (e.g. DigiLocker redirect), the iFrame may also post structured events such as `PARTNER_MERCHANT_VERIFICATION_REDIRECT`. See [Partner Onboarding Events](/guides/partner-onboarding-events) for the full event reference.

    **Option B — callBackUrl redirect**

    After the merchant finishes, PayGlocal redirects the iFrame to the `callBackUrl` you provided. Your page at that URL can render a completion screen.

    <Warning>
      After the iFrame callback, **always perform a server-to-server status check** by calling `GET /gcc/v2/partner/merchant/onboard/{onboardingId}/status` to confirm that `vkyc` and `digiLocker` statuses are `COMPLETE`. Do not rely on the callback redirect alone to confirm completion.
    </Warning>
  </Step>
</Steps>

***

## Technical Requirements and Best Practices

<Warning>
  The parent page hosting the iFrame **must be served over HTTPS**. Modern browsers block camera and microphone access on insecure (HTTP) origins, which will break VKYC.
</Warning>

| Requirement                   | Detail                                                                                                                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **HTTPS**                     | Parent page must use HTTPS. HTTP origins will block camera/microphone access.                                                         |
| **Minimum height**            | Set the iFrame container to at least **700px** height to prevent internal scrollbars during the VKYC video call.                      |
| **Permissions Policy header** | Ensure your server does not send a `Permissions-Policy: camera=()` or similar header that conflicts with iFrame permissions.          |
| **Origin validation**         | Validate `event.origin` against `https://uat.dashboard.payglocal.in` (UAT) or `https://dashboard.payglocal.in` (Production).          |
| **Server-side confirmation**  | After callback, always call `GET /status` server-to-server to confirm the final merchant state.                                       |
| **Token expiry**              | Session tokens in `redirectLink` expire after 24 hours. Generate a fresh link if the merchant does not complete verification in time. |
| **Responsive design**         | The verification suite is mobile-responsive. Your container should be flexible-width with a fixed minimum height.                     |

***

## Complete Frontend Example

```html theme={null}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Merchant Verification</title>
  <style>
    #pg-iframe-wrapper {
      width: 100%;
      max-width: 1000px;
      height: 800px;
      margin: 0 auto;
    }
    #payglocal-onboarding-ui {
      width: 100%;
      height: 700px;
      border: 1px solid #e0e0e0;
      border-radius: 8px;
    }
  </style>
</head>
<body>
  <div id="pg-iframe-wrapper">
    <iframe
      id="payglocal-onboarding-ui"
      allow="camera; microphone; geolocation"
      frameborder="0">
    </iframe>
  </div>

  <script>
    const ALLOWED_ORIGINS = [
      "https://uat.dashboard.payglocal.in",
      "https://dashboard.payglocal.in"
    ];

    // Step 1: Fetch the redirectLink from your backend (which calls the PayGlocal redirect API)
    fetch("/api/get-verification-url?onboardingId=YOUR_ONBOARDING_ID")
      .then(res => res.json())
      .then(data => {
        document.getElementById("payglocal-onboarding-ui").src = data.redirectLink;
      });

    // Step 2: Listen for completion signal from PayGlocal
    window.addEventListener("message", function(event) {
      if (!ALLOWED_ORIGINS.includes(event.origin)) return;

      if (event.data === "PARTNER_MERCHANT_VERIFICATION_COMPLETE") {
        // Step 3: Trigger a server-side status check before updating UI
        fetch("/api/check-onboarding-status?onboardingId=YOUR_ONBOARDING_ID")
          .then(res => res.json())
          .then(status => {
            if (status.vkyc === "COMPLETE" && status.digiLocker === "COMPLETE") {
              console.log("Verification complete. Redirecting...");
              window.location.href = "/onboarding-success";
            }
          });
      }
    }, false);
  </script>
</body>
</html>
```