Iframe Integration

Embed the flow within your web page using an iframe, so users complete the process without leaving your application.

Prerequisites

• Generate a launch URL by calling the Initiate Flow API as described in the Browser Integration document

Iframe Setup

Add the following iframe element to your page:

<iframe
    id="oneKYCIframe"
    sandbox="allow-same-origin allow-scripts"
    allow="camera"
    title="OneKYC QR Screen"
></iframe>

Parent–Iframe Communication

The iframe and your parent page communicate using window.postMessage. This section covers the two message exchanges: establishing a trusted origin, and receiving callbacks when the flow ends.

Establish the Trusted Origin

The IAB application inside the iframe sends a GET_ORIGIN_FROM_ONEKYC message to your parent page. Your page responds with its origin, which the IAB stores as trustedOrigin for secure communication.

In the iframe (IAB)

let trustedOrigin

window.parent.postMessage({ type: 'GET_ORIGIN_FROM_ONEKYC' }, '*');

window.addEventListener('message', (event) => {
  if (event.data.type === 'SEND_ORIGIN_TO_ONEKYC') {
    trustedOrigin = event.origin;
  }
});

In the parent (Partner)

window.addEventListener('message', (event) => {
  if (event.data?.type === 'GET_ORIGIN_FROM_ONEKYC') {
     // Respond to the iframe
     event.source.postMessage({ type: 'SEND_ORIGIN_TO_ONEKYC' }, event.origin);
  }
})

Receive the Flow Callback

The IAB sends a callback to your parent page when the user completes the submission or closes the screen.

In the iframe (IAB)

window.parent.postMessage({ 
  type: 'ONEKYC_QR_CALLBACK',
  data: { status: 'COMPLETED', partner_session_id: 'xxx' } 
}, trustedOrigin);

In the parent (Partner)

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://web-app.goidentitas.id' || event.data.type !== 'ONEKYC_QR_CALLBACK')
		return;
  console.log('Status received from OneKYC:', event.data.status);
});

Callback Values

Every callback includes type: 'ONEKYC_QR_CALLBACK' with a data object containing status, partner_session_id, and an optional error_code: