iFrame Integration - PayGlocal Developers

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)

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

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

Initialize — Generate the verification session URL

Before rendering the iFrame, call the Get Verification Redirect API from your backend to generate a session URL for the merchant.

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:

{
  "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.

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.

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.

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

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

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.

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 for the full event reference.Option B — callBackUrl redirectAfter the merchant finishes, PayGlocal redirects the iFrame to the callBackUrl you provided. Your page at that URL can render a completion screen.

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.

Technical Requirements and Best Practices

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.

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

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

​Step 1: Domain Whitelisting (Action Required)

​Step 2: Integration Workflow

​Technical Requirements and Best Practices

​Complete Frontend Example

Step 1: Domain Whitelisting (Action Required)

Step 2: Integration Workflow

Technical Requirements and Best Practices

Complete Frontend Example