Partner Onboarding Events

PayGlocal provides two channels for partners to track merchant onboarding progress:

Channel	Delivery	Best for
UI Events (postMessage)	Browser → parent page	Real-time UX updates while the iFrame is open
Webhooks	Server → your endpoint	Reliable async notifications for backend workflows

Always confirm the final onboarding state with a server-side Get Onboarding Status call. Neither UI events nor webhooks alone should be treated as the source of truth for go-live decisions.

UI Events (iFrame postMessage)

When you embed the PayGlocal verification iFrame, the verification page communicates with your parent page using the browser’s postMessage API.

Listening for completion

window.addEventListener("message", (event) => {
  const allowedOrigins = [
    "https://uat.dashboard.payglocal.in",
    "https://dashboard.payglocal.in"
  ];
  if (!allowedOrigins.includes(event.origin)) return;

  console.log("Message received:", event.data);

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

Event value	Meaning
`PARTNER_MERCHANT_VERIFICATION_COMPLETE`	Merchant has finished the full verification flow (T&C, DigiLocker, VKYC)

During intermediate steps, the iFrame may also emit structured events:

{
  eventName: "PARTNER_MERCHANT_VERIFICATION_REDIRECT",
  eventData: {
    uri: "https://...",
    stepName: "DIGILOCKER",
    subStepId: "CONSENT_PROCEED"
  }
}

Best practices

Validate event.origin — only accept messages from https://uat.dashboard.payglocal.in (UAT) or https://dashboard.payglocal.in (Production). The iFrame loads the PayGlocal dashboard partner onboarding experience, not a separate verify subdomain.
Follow with GET /status — the postMessage signals UI completion; confirm vkyc, digiLocker, and onboardingStatus server-side before updating your merchant record.
See iFrame Integration for the full embed workflow.

Webhook Events

PayGlocal sends server-side webhook notifications to URLs configured in your PayGlocal Partner Dashboard. Webhooks fire for partner-assisted merchant onboardings only. Configure which events you receive via POST /gcc/v2/partner/{resellerMid}/webhook. List available event types with GET /gcc/v2/partner/webhook.

Supported events

Event	When fired	Description
`MERCHANT_DIGILOCKER_CKYC_COMPLETED`	DigiLocker or CKYC verification completes	Identity verification step finished
`MERCHANT_TERMS_AND_CONDITIONS_ACKNOWLEDGED`	Merchant accepts T&C	Terms and conditions acknowledged
`MERCHANT_VKYC_COMPLETED`	VKYC session completes	Video KYC finished
`MERCHANT_STATUS_ACCEPTED`	Merchant is activated	Onboarding approved and merchant goes live
`MERCHANT_PENDENCY_STATUS_UPDATED`	Pendency status changes	Document or compliance pendency updated

System-created pendencies with status UNDER_REVIEW are not sent to partners. Only partner-visible pendency updates trigger this webhook.

Webhook Payload Structure

All onboarding webhook payloads are flat key-value maps (Map<String, String>).

Common fields (all events)

Field	Type	Description
`onboarding_id`	string	PayGlocal onboarding ID
`onboarding_status`	string	Current `NewOnboardingStatus` value
`event_timestamp`	string	Unix epoch milliseconds when the event was generated
`status`	string	Event type name (matches the event enum)

Event-specific fields

MERCHANT_STATUS_ACCEPTED

Field	Description
`merchant_id`	Activated merchant ID (UCIC)
`event_timestamp`	Go-live timestamp (overwritten with go-live time)

MERCHANT_TERMS_AND_CONDITIONS_ACKNOWLEDGED

Field	Description
`terms_and_conditions_acknowledged`	`"true"`

MERCHANT_VKYC_COMPLETED

Field	Description
`vkyc_completed`	`"true"`

MERCHANT_DIGILOCKER_CKYC_COMPLETED

Field	Description
`digilocker_ckyc_completed`	`"true"`

MERCHANT_PENDENCY_STATUS_UPDATED

Field	Description
`pendency_info_category`	Pendency category
`pendency_info_sub_category`	Pendency sub-category
`pendency_info_reason`	Reason for the pendency
`pendency_info_status`	Current pendency status
`pendency_info_creation_time`	When the pendency was created
`pendency_info_cards_approval_blocking`	`"true"` / `"false"` — blocks card approval
`pendency_info_mca_approval_blocking`	`"true"` / `"false"` — blocks MCA approval

Example payload — VKYC completed

{
  "onboarding_id": "pg_onboard_abc123",
  "onboarding_status": "UNDER_REVIEW",
  "event_timestamp": "1717238400000",
  "status": "MERCHANT_VKYC_COMPLETED",
  "vkyc_completed": "true"
}

Example payload — Merchant accepted

{
  "onboarding_id": "pg_onboard_abc123",
  "onboarding_status": "ACCEPTED",
  "event_timestamp": "1717324800000",
  "status": "MERCHANT_STATUS_ACCEPTED",
  "merchant_id": "merchant_xyz789"
}

Recommended Integration Pattern

Partner completes onboard API steps (business details → products)
Partner calls GET Verification Redirect → embeds iFrame
Parent page listens for PARTNER_MERCHANT_VERIFICATION_COMPLETE postMessage
Partner backend receives webhook events asynchronously
Partner backend calls GET /status to confirm final state
Partner updates merchant record in their system

iFrame Integration

Embed the verification flow and handle postMessage events.

Get Onboarding Status

Confirm final merchant state server-side.

API Flow Overview

End-to-end onboarding sequence.

Introduction

Onboarding

Dashboard

Integration

Integration Resources

Merchant store plugins

MCA Integration

UI Events (iFrame postMessage)

Listening for completion

Best practices

Webhook Events

Supported events

Webhook Payload Structure

Common fields (all events)

Event-specific fields

Example payload — VKYC completed

Example payload — Merchant accepted

Recommended Integration Pattern

iFrame Integration

Get Onboarding Status

API Flow Overview

​UI Events (iFrame postMessage)

​Listening for completion

​Best practices

​Webhook Events

​Supported events

​Webhook Payload Structure

​Common fields (all events)

​Event-specific fields

​Example payload — VKYC completed

​Example payload — Merchant accepted

​Recommended Integration Pattern

iFrame Integration

Get Onboarding Status

API Flow Overview

UI Events (iFrame postMessage)

Listening for completion

Best practices

Webhook Events

Supported events

Webhook Payload Structure

Common fields (all events)

Event-specific fields

Example payload — VKYC completed

Example payload — Merchant accepted

Recommended Integration Pattern