Skip to main content

KYC Verification via IFrame Integration

This documentation outlines how to integrate the KYC (Know Your Customer) process into your website using an embedded IFrame. It covers the session initialization, IFrame embedding with query parameters, and handling the verification result via postMessage.

1. Initialize a KYC Session​

Your client application must start a KYC session by making a POST request to the API endpoint:

POST https://authenticalls.com/kyc/client/api/sessions/start
Content-Type: application/json
Authorization: Bearer <YOUR_API_KEY>

Request Payload (JSON): For the payload schemas, refer to Customer Data Payload documentation

Response (JSON):

{
  "sessionId": "<SESSION_ID>"
}

2. Embed the IFrame​

Once you receive the sessionId, display the IFrame and set its src to the KYC application URL:

<iframe
  id="kycFrame"
  allow="camera; microphone"
  style="max-width: 639px; min-height: 600px;"
></iframe>

The iframe's maximum suggested width is 639px and minimum height 600px

// After obtaining sessionId:
const integratorOrigin = location.origin;
document.getElementById("kycFrame").src =
  `https://authenticalls.com/kyc/client/app/intro` +
  `?sessionId=${sessionId}` +
  `&iframe` +
  `&integrator=${integratorOrigin}`;

Query Parameters

  • sessionId (required): The unique session identifier returned by the API.
  • iframe (flag): When present, instructs the KYC app to render in IFrame mode.
  • integrator (required, if iframe is also present): The URL origin of your website (URL-encoded). Used to instruct the iframe to send the final result message.

3. Handling the KYC Result with postMessage​

When the KYC process completes, the IFrame will send a message to the parent window:

window.addEventListener("message", (event) => {
  // 1. Validate the message origin
  if (event.origin !== "https://authenticalls.com") return;

  // 2. Process only KYC finished events
  if (event.data.type === "kyc_finished") {
    const resultPayload = event.data.payload;
    console.log("KYC finished:", resultPayload);
    // Your custom logic (e.g., navigate, display results)
    alert("KYC result ready!");
  }
});

The type of event.data.payload is the same as the return type of Get KYC Verdict

Important Notes

  • Origin Check: Always verify event.origin to ensure messages come from https://authenticalls.com.
  • type Field: Only messages with type === 'kyc_finished' indicate completion.

Full Integration Flow​

  1. User fills out the KYC form on your site.
  2. Your client code calls /sessions/start and retrieves sessionId.
  3. Show the IFrame container and set its src with sessionId, iframe, and integrator parameters.
  4. The user completes KYC in the embedded IFrame.
  5. The IFrame posts a kyc_finished message back to your page.
  6. Your page listens for this message, validates it, and handles the result accordingly.

With this setup, you can seamlessly embed the KYC workflow into your website, leveraging camera and microphone permissions directly within an IFrame, and safely receive the results via postMessage.