vycheck()

vycheck() starts a verification. In the default redirect mode it mints a session and sends the user to the hosted flow. In the iframe modes it opens the flow over or inside your page and resolves with the result when the user finishes.

import { init, vycheck } from "@verifyyou-sdk/client";

init({ publishableKey: "pk_test_…" }); // once, at app startup

verifyButton.addEventListener("click", () => vycheck());

Wire it to a user action like a button click. Don’t auto-open the flow on page load.

What it does

vycheck() is the client-side counterpart to the server’s POST /v3/initialize. Under the hood it calls that endpoint with your publishable key, then either navigates to the returned URL (redirect mode) or mounts it in an iframe (drawer and inline modes). The mode comes from init().

Redirect mode: the page navigates away.

The returned promise never resolves because the browser leaves the page. When the user comes back, the result is on the URL. Read it with vyget() on page load.

Iframe modes: the promise resolves in place.

The flow opens as a drawer or inside your container. When it finishes, vycheck() resolves with the result and your onComplete callback fires. If the user dismisses the flow, it resolves with an empty result and onClose fires.

Either way, confirm on your backend.

Send the token to your server and exchange it with GET /v3/confirmations/{token} before granting anything.

Signature

function vycheck(overrides?: VyCheckOptions): VyCheckHandle;

// A promise for the result, with close() to tear an embed down early.
interface VyCheckHandle extends Promise<VyResult> {
  close(): void;
}

interface VyResult {
  token: string | null;    // the vyt confirmation token; confirm it server-side
  verified: boolean;       // UI hint from vyc; never gate access on this
  vyc: string | null;      // raw verdict code: "1", "0", or null
}

VyCheckOptions

Optional per-call overrides for anything you set in init(), except the publishable key and the mode. Useful for a one-off container, a different onComplete, or a session minted on your server (below).

In iframe modes the promise resolves with the result. On dismiss it resolves with { token: null, verified: false, vyc: null } rather than rejecting, so you don’t need a try/catch around the await.

Typical usage, drawer mode

import { init, vycheck } from "@verifyyou-sdk/client";

init({ publishableKey: "pk_test_…", mode: "iframe" });

verifyButton.addEventListener("click", async () => {
  const { token } = await vycheck();
  if (!token) return; // dismissed without finishing

  // Confirm on your backend, then unlock the UI on its answer.
  const res = await fetch("/api/verify/confirm", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ token }),
  });
  const { verified } = await res.json();
  if (verified) showGatedContent();
});

Returning users

If the person already passed this verification, the flow can complete almost instantly and hand back a fresh token. That is the skip window on your verification’s configuration doing its job, not a bug. Each pass still gets its own token and needs its own backend confirmation.

vycheck() only starts verification. The result still has to be confirmed server-side. Never grant access from the client-side result alone.

Run a session minted on your server

To attach your own user id or bind an email or phone the user can’t change, mint the session on your server with POST /v3/initialize and a secret key, then pass the returned session_id to vycheck:

// Browser: fetch a session_id from your backend, then embed it.
init({ publishableKey: "pk_live_…", mode: "iframe" });

const { session_id } = await fetch("/api/verify/start").then((r) => r.json());
const { token } = await vycheck({ session: session_id });
if (token) confirmOnServer(token);

The publishable key set in init() goes unused here: the session already carries its config, external_id, and any bound identity from initialize. Parameters like external_id and pass_params only exist on the server call.

Close an embed early

vycheck() returns a handle you can close() to tear a drawer or inline embed down before the user finishes, for example when they navigate away:

const handle = vycheck({ session: session_id });
cancelButton.addEventListener("click", () => handle.close());

const { token } = await handle; // resolves empty if you closed it

close() is a no-op in redirect mode.

A session override runs the flow in an iframe. Set mode: "iframe" in init() so the embed has somewhere to mount.

Verification processes

SDK and API

Advanced usage

Reference

What it does

Signature

Typical usage, drawer mode

Returning users

Run a session minted on your server

Close an embed early

​What it does

​Signature

​Typical usage, drawer mode

​Returning users

​Run a session minted on your server

​Close an embed early

What it does

Signature

Typical usage, drawer mode

Returning users

Run a session minted on your server

Close an embed early