KYC Verification via IFrame Integration
This guide shows how to embed the hosted KYC (Know Your Customer) flow in your website with an IFrame. It covers starting a session, embedding the IFrame, reacting to the completion message sent through postMessage, and retrieving the result.
This guide uses the current KYC endpoints, under /v1/digital-onboarding. They replace the /sessions/start and /sessions/verdict endpoints, which are deprecated.
1. Start a KYC Session (from your backend)
Start a session by sending a POST request from your backend. Never call this endpoint from the browser: your API key would be exposed to anyone visiting your page.
POST https://authenticalls.com/kyc/client/api/v1/digital-onboarding/start
Content-Type: application/json
Authorization: Bearer <YOUR_API_KEY>
Request Payload (JSON):
{
"country": "RO",
"type": "id-card",
"customerId": "customer-123",
"withLiveness": true,
"runNationalRegistryLookup": false,
"runDocumentProof": false
}
country(required): ISO alpha 2 code of the country that issued the document.type(required): The type of the document the user will capture (e.g.id-card,passport,driving-license).customerId(optional): Your internal identifier for the user, returned with the result.withLiveness(optional, defaultfalse): Whether the user also takes liveness selfies, matched against the document photo.runNationalRegistryLookup(optional, defaultfalse): Whether to also look the individual up in the national registry.runDocumentProof(optional, defaultfalse): Whether to also run Document Proof (anti-spoofing) on the document images.
For the full schema, see the start session API reference. For the accepted country and document combinations, see All Countries.
Response (JSON):
{
"sessionId": "<SESSION_ID>"
}
Return the sessionId to your frontend. It is safe to expose: it only lets the user go through the flow, and does not give access to the result.
2. Embed the IFrame
Add the IFrame to your page. The allow="camera; microphone" attribute is required, since the user captures their document (and selfies) with the camera.
<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.
Responsive styling for mobile
To make the IFrame take the full screen on mobile devices, add the following CSS:
/* Desktop default */
#kycFrame {
width: 100%;
max-width: 639px;
min-height: 600px;
}
/* Mobile full screen */
@media (max-width: 768px) {
#kycFrame {
width: 100vw !important;
height: 100svh !important;
max-width: none;
border: none;
position: fixed;
top: 0;
left: 0;
z-index: 9999;
}
}
Once your frontend has the sessionId, set the IFrame's src:
// After obtaining sessionId from your backend:
const integratorOrigin = encodeURIComponent(location.origin);
document.getElementById("kycFrame").src =
`https://authenticalls.com/kyc/client/app/intro` +
`?sessionId=${sessionId}` +
`&iframe` +
`&integrator=${integratorOrigin}`;
Query Parameters
sessionId(required): The session identifier returned when starting the session.iframe(flag): When present, the app renders in IFrame mode.integrator(required withiframe): The URL-encoded origin of your website (e.g.https://yourapp.com). The completion message is only sent to this origin.
Desktop users and the QR code
On desktop, the first screen offers the user to continue on their phone by scanning a QR code, or to continue on the current device. If they scan it, keep the IFrame open: it waits for the phone to finish, then sends the completion message as usual.
3. Handle the Completion Message with postMessage
When the KYC process completes, the IFrame sends a message to the parent window:
window.addEventListener("message", async (event) => {
// 1. Only accept messages from our origin
if (event.origin !== "https://authenticalls.com") return;
// 2. Only handle the KYC completion message
if (event.data?.type !== "digital_onboarding_finished") return;
const { id, status } = event.data.payload;
// 3. Optional: hide the IFrame before it shows its own result screen
document.getElementById("kycFrame").style.display = "none";
// 4. Ask your backend to retrieve the full result (see step 4)
await fetch(`/api/kyc/${id}/result`);
});
The message has the following shape:
{
"type": "digital_onboarding_finished",
"payload": {
"id": "<SESSION_ID>",
"status": "Completed"
}
}
id: The KYC session id, which is also the key of its result.status: One ofCompleted,PartiallyCompleted(some of the operations failed and were refunded) orFailed.
Important Notes
- The message does not contain the result. It only carries the session id and status, since the result holds the user's document data. Retrieve the result from your backend (step 4), and do not base any decision on the message alone: anyone can open your page and send messages to it.
- Origin check: Always verify that
event.originishttps://authenticalls.com. - Hiding the IFrame: The IFrame waits about 1 second after sending the message before showing its own result screen. Use that time to hide it if you want to show your own UI instead.
- Failures: When the processing fails on the same device, the IFrame shows an error screen and no message is sent. Use the webhook as the reliable completion signal on your backend.
4. Retrieve the Result (from your backend)
Use the session id to retrieve the full result with your API key:
GET https://authenticalls.com/kyc/client/api/v1/digital-onboarding/result?digitalOnboardingSessionId=<SESSION_ID>
Authorization: Bearer <YOUR_API_KEY>
The result contains the status, the optional customerId, the Document Analysis (the data extracted from the document) and, depending on the options the session was started with, the Face Match and the national registry lookup. See the get result API reference for the response structure.
5. Optional: Webhook Notification
You can also receive a server-side webhook when a KYC session is processed. Configure your webhook URL on your integration in the dashboard. We recommend also generating a webhook secret, so the requests are signed and you can verify their signature.
POST {webhook_url}
Content-Type: application/json
Payload:
{
"id": "<WEBHOOK_EVENT_ID>",
"event": "digital_onboarding.completed",
"sandbox": false,
"data": {
"digitalOnboardingResult": {
"id": "<SESSION_ID>",
"status": "Completed",
"customerId": "customer-123"
// ...same structure as the get result response
},
"integration": {
// ...the integration the session belongs to
}
}
}
data.digitalOnboardingResult has the same structure as the get result response, so you can process the result directly from the webhook.
For integrations without a webhook secret, the fields under
dataare also duplicated at the top level of the payload. This is deprecated, and will be removed after January 31, 2027 (UTC). Read the event data fromdata.
Full Integration Flow
- Your backend starts a session with
POST /v1/digital-onboarding/startand returns thesessionIdto your frontend. - Your frontend shows the IFrame, with
sessionId,iframeandintegratorin itssrc. - The user captures their document (and selfies, with
withLiveness) in the IFrame, on the same device or on their phone through the QR code. - The IFrame posts a
digital_onboarding_finishedmessage to your page. - Your page validates the message origin and type, hides the IFrame, and asks your backend for the result.
- Your backend retrieves the result with
GET /v1/digital-onboarding/result, or processes thedigital_onboarding.completedwebhook.