Website Redirect

The website redirect is the lightest way to add identity verification to a web platform. Instead of embedding capture components, you send the user to the IDV Platform hosted verification app, they complete the flow there (selfie + identity document), and they are redirected back to your site with the result. Your backend receives the verified customer data through a callback.

The same hosted app can also be embedded as an iframe instead of a full-page redirect — the setup is nearly identical and both are covered below.

When to use it

You want verification live quickly, with minimal front-end work.
You don't need to embed capture inside your own branded UI (for that, use Web Components or the Mobile SDK).
A browser-based journey is acceptable, with the hosted app handling capture, quality guidance, and processing.

Prerequisites

Verification runs against your registered configuration. Contact your Innovatrics representative and provide:

Value	Purpose
`verifiedUrl`	Where the user is redirected after a successful verification.
`rejectedUrl`	Where the user is redirected when the result is rejected/failed.
`unverifiedUrl`	Where the user is redirected when they cancel.
`callbackUrl`	Where the platform POSTs the sensitive customer data on success (your backend).
`logoUrl`	Your logo, shown in the hosted app (SVG for light background recommended; PNG supported).
`CUSTOMER_NAME`	Your identifier, good practice for identification.

In return you receive, per environment, your OAuth2 client credentials (managed in Integration Settings), the API service URL, and the hosted app URL.

A backend is required

The OAuth2 client secret must never live in front-end code — public front-ends would expose it and allow your account to be abused. Your backend authenticates, obtains the token, and calls the API. The front-end only performs the redirect.

How it works

At a high level, the data flows like this:

The user starts verification on your website.
Your website asks your backend for a session token.
Your backend obtains an access token (OAuth2 client-credentials) and calls the IDV Platform API to create a session.
The API returns a sessionToken; your backend passes it back to the website.
The website sends the user to the hosted verification app (redirect) or embeds it (iframe), passing the sessionToken.
The user completes the verification (selfie + identity document) in the hosted app.
On success, the API POSTs the sensitive customer data to your callbackUrl; your backend stores it and acknowledges with 204 No Content.
The hosted app returns the user to your site with the result — as query parameters (redirect) or a postMessage (iframe).

Integration steps

1. Get an access token (backend)

Authentication uses the same OAuth2 model as the rest of the IDV Platform (see Capture & Workflow API → Authentication). Your backend requests an access token with the client-credentials grant, using the client credentials provisioned in Integration Settings. Keep the token server-side; it is short-lived, so cache it and refresh it before expiry.

const response = await fetch(`${TOKEN_URL}/oauth/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
  }),
});
const { access_token } = await response.json();

2. Create a session (backend)

Exchange the access token for a session token, optionally specifying the locale for the hosted app.

const response = await fetch(`${SERVICE_URL}/api/v1/session`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${access_token}`,
  },
  body: JSON.stringify({
    configuration: { locale: 'en' },
  }),
});
const { sessionToken } = await response.json(); // return this to the front-end

3. Send the user to the hosted app (front-end)

Redirect flow — navigate the browser to the hosted app with the session token:

window.location.href = `${APP_URL}/?sessionToken=${sessionToken}`;

Iframe flow — embed the hosted app instead, adding viewType=iframe:

const iframe = document.createElement('iframe');
iframe.src = `${APP_URL}?sessionToken=${sessionToken}&viewType=iframe`;
iframe.width = '100%';
iframe.height = '100%';
iframe.allow = 'camera';
iframe.style.border = 'none';
document.body.appendChild(iframe);

4. The user verifies

In the hosted app the user provides a selfie and a photo of their identity document. The app uploads and processes them, then returns the outcome.

Getting the result

The overall outcome is delivered to the front-end, and the sensitive customer data is delivered to your backend.

Outcome (front-end)

Both flows return the same result — a timestamp (used to check result integrity) and a status of success or failed.

Redirect flow — the user returns to verifiedUrl, rejectedUrl, or unverifiedUrl with the result as query parameters. The user may not land on the page they started from.
```
https://your-site.com/verified?timestamp=1702039347154&status=success
```

Iframe flow — the result is delivered via postMessage to the page that started verification. Always validate the message origin (it is derived from your verifiedUrl):

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://your-site.com') return;
  const { data } = event; // { timestamp, status }
});

Customer data (backend callback)

Before the user is redirected back, the platform POSTs the verified customer data to your callbackUrl. Your backend must store it securely and respond 204 No Content to acknowledge receipt.

The event has a event type (currently VERIFICATION_SUCCEEDED) and a data payload:

Field	Description
`sessionToken`	Identifier of the session.
`result`	Overall status — always `VERIFIED` for this event.
`timestamp`	Verification timestamp (for integrity checks).
`customer.fullName`	Full name of the verified user.
`customer.dateOfBirth`	Date of birth.
`customer.placeOfBirth`	Place of birth.
`customer.address.fullAddress`	Full address.
`customer.documentNumber`	Document number of the verified ID.
`customer.dateOfExpiry`	Document expiry date.
`customer.selfie`	Base64-encoded selfie.

type VerificationSucceededResult = {
  customer: {
    address: { fullAddress?: string };
    documentNumber?: string;
    dateOfBirth?: string;
    dateOfExpiry?: string;
    fullName?: string;
    placeOfBirth?: string;
    selfie: string;
  };
  timestamp: string;
  result: string;        // 'VERIFIED'
  sessionToken?: string;
};

Error handling

Errors surface as HTTP status codes and are handled inside the hosted app; you only need to handle errors during app initialization and while retrieving the result. For security, the hosted app does not expose error details — each error carries a unique tracing ID. If you hit an error, contact Innovatrics with that tracing ID for analysis.

When to use it​

Prerequisites​

How it works​

Integration steps​

1. Get an access token (backend)​

2. Create a session (backend)​

3. Send the user to the hosted app (front-end)​

4. The user verifies​

Getting the result​

Outcome (front-end)​

Customer data (backend callback)​

Error handling​

See also​