Hosted flow

The hosted flow is a page we run and maintain that walks the user through every step of your flow. It handles camera permissions, capture quality, retries, localisation, right-to-left layouts and accessibility, so you write no front-end code at all.

The shape of the integration

Your backend creates a verification and receives hosted_verify_url. You send the user there. When they finish, they are returned to your return_url and TrustWix sends you the result by webhook.

Your backend

const res = await fetch("https://api.trustwix.com/v1/verifications", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRUSTWIX_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `kyc-${user.id}`,
  },
  body: JSON.stringify({
    flow: "flw_id_and_liveness",
    applicant: { reference_id: user.id },
    locale: user.locale,
    return_url: "https://your-app.example/kyc/done",
  }),
});

const verification = await res.json();
await db.users.update(user.id, { verificationId: verification.id });
// Redirect the user, or email them the link.
return Response.redirect(verification.hosted_verify_url);

The return URL is not the result

When the user lands back on return_url they have finished submitting, which is not the same as having been decided. Checks may still be running. Show a neutral "we are reviewing this" state and let the webhook drive the real transition.

Never grant access on the return redirect

The redirect is a navigation event the user controls. The webhook is the authenticated, server-to-server statement of fact. Only the webhook may unlock anything.

Session lifetime

hosted_verify_url is valid until expires_at. If the user abandons the session and comes back after it expires, create a new verification rather than trying to revive the old one. The expired one stays in your history with status of expired.

Cross-device handoff

A user who starts on a desktop without a usable camera can continue on their phone. The hosted flow offers this itself and carries the same session across, so you do not need to create a second verification or coordinate anything. The verification id, and therefore your webhook handling, is unchanged.

Sending the link yourself

You do not have to redirect. hosted_verify_url is a normal URL, so you can email or message it, which suits back-office onboarding where the person being verified is not the person sitting at the screen. Pass applicant.email if you want TrustWix to be able to contact them about the session.