Concepts

Web SDK

The VerifyMe Web SDK opens the hosted, tenant-branded flow inside your page as a modal, an inline frame, a popup or a full-page redirect, and reports progress through events. One script tag, no dependencies, no build step.

Installation

<script src="https://kyc.example.com/sdk/v1/verifyme.js"></script>

The script defines the global window.VerifyMe (it is also safe to require() in a CommonJS bundler). It is served with Access-Control-Allow-Origin: * and Cross-Origin-Resource-Policy: cross-origin, so it works with crossorigin and strict cross-origin isolation setups. It uses ES5 syntax and runs in all evergreen browsers.

Quick start

VerifyMe.init({
  publicKey: "vm_pk_test_xxxxxxxxxxxxxxxxxx",
  onComplete: (r) => console.log("submitted", r.requestId, r.status),
  onClose: (c) => console.log("closed", c.reason),
  onError: (e) => console.warn(e.code, e.message),
});

document.getElementById("verify").addEventListener("click", () => {
  VerifyMe.open({ url: onboardingUrlFromYourServer, mode: "modal" });
});

init(options)

VerifyMe.init(options) configures the SDK and returns VerifyMe. It is idempotent: calling it again merges the new options into the old ones.

open(options)

VerifyMe.open(options) starts the flow and returns true if it was started. Failures are never thrown; they arrive as error events.

Modes

If the hosted page does not report ready within 8 seconds (typically because framing is blocked for your origin), the SDK emits error FRAME_TIMEOUT, then fallback { to: "popup" } and, if the popup is blocked, fallback { to: "redirect" }, so the applicant is never left on a blank frame. Set fallback: false to handle this yourself.

Other methods

Events

Events arrive through onEvent, the specific callbacks (onComplete, onClose, onError) and VerifyMe.on(type, fn).

{ "type": "step", "data": { "stepKey": "pan", "stepType": "PanVerification", "status": "completed", "completed": 3, "total": 6 } }

Error codes

postMessage protocol

You normally never touch this; the SDK does it. It is documented so you can audit it or embed the iframe yourself.

1. The parent (SDK) sends { source: "verifyme-host", type: "init", origin: <your page origin> } to the hosted page, repeatedly (every 400 ms, up to 25 times) until it receives ready. The target origin is the VerifyMe origin.
2. The hosted page checks that event.source is its parent (or its opener, for popups) and that event.origin equals the origin the message claims. Only then does it remember that origin and post only to it. Before the handshake it posts only to the document.referrer origin, if there is one.
3. The hosted page sends { source: "verifyme", type, ...data } where type is ready, step, submitted, closed or error.
4. The SDK accepts a message only if event.origin equals the configured host origin and event.source is its own iframe or popup window, and source === "verifyme".

// Minimal listener if you embed the iframe yourself
window.addEventListener("message", (e) => {
  if (e.origin !== "https://kyc.example.com") return;
  if (e.source !== iframe.contentWindow) return;
  const m = e.data;
  if (!m || m.source !== "verifyme") return;
  if (m.type === "submitted") showPending(m.requestId);
});
// ...and complete the handshake so the page knows where to send messages:
iframe.contentWindow.postMessage(
  { source: "verifyme-host", type: "init", origin: location.origin },
  "https://kyc.example.com"
);

Framing, CSP and permissions

Popup versus modal versus redirect

Accessibility

The modal is an accessible dialog: focus moves into it and is trapped, background content is made inert and page scroll is locked, Esc closes it (the hosted page forwards Esc pressed inside the frame as closed with reason escape), focus returns to the control that opened it, and safe-area insets are respected on notched phones. The SDK close button is hidden once the hosted UI shows its own. The frame has the title "Identity verification". Provide a visible, labelled button that opens the flow, and announce completion to assistive technology yourself in onComplete.

Versioning, SRI and migration

• The script path is versioned: /sdk/v1/verifyme.js. Breaking changes will ship under /sdk/v2/; v1 only receives backwards compatible fixes. The file is cacheable for about five minutes.
• Subresource Integrity. The v1 file can change with compatible fixes, so an SRI hash on it will eventually break. If your policy requires SRI, self-host a copy you have reviewed: openssl dgst -sha384 -binary verifyme.js | openssl base64 -A, then <script src="/static/verifyme.js" integrity="sha384-..." crossorigin="anonymous"></script>.
• Migrating from a plain redirect: keep your server code and returnUrl. Add the script and replace res.redirect(onboardingUrl) with VerifyMe.open({ url, mode: "modal" }). Leave the webhook handling untouched.
• Migrating from your own iframe: remove your postMessage code, delete the allow attributes you set and call VerifyMe.open. Add your origin to Allowed origins.

Complete example

Three files: a tiny Express server that creates the request, an HTML page and an external script (inline scripts would violate a strict CSP).

// npm i express    (Node 18+)
import express from "express";

const HOST = process.env.VERIFYME_HOST;        // https://kyc.example.com
const KEY = process.env.VERIFYME_API_KEY;      // vm_test_...  (secret, server only)

const app = express();
app.use(express.static("public"));

app.post("/api/kyc/start", async (req, res) => {
  const r = await fetch(`${HOST}/v1/onboarding-requests`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `demo-${Date.now()}`,
    },
    body: JSON.stringify({ externalReference: `demo-${Date.now()}`, mobile: "9876541234" }),
  });
  if (!r.ok) return res.status(502).json({ error: "could_not_start" });
  const { requestId, onboardingUrl } = await r.json();
  res.json({ requestId, onboardingUrl });         // never send the API key to the browser
});

app.listen(3000, () => console.log("http://localhost:3000"));

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <title>Verify your identity</title>
</head>
<body>
  <main>
    <h1>Verify your identity</h1>
    <button id="verify" type="button">Start verification</button>
    <p id="status" role="status" aria-live="polite"></p>
  </main>

  <script src="https://kyc.example.com/sdk/v1/verifyme.js"></script>
  <script src="/kyc.js"></script>
</body>
</html>

const statusEl = document.getElementById("status");
const button = document.getElementById("verify");

VerifyMe.init({
  publicKey: "vm_pk_test_xxxxxxxxxxxxxxxxxx",
  onEvent: ({ type, data }) => console.debug("[verifyme]", type, data),
  onComplete: ({ requestId }) => {
    statusEl.textContent = "Thanks. We are verifying your details.";
    button.hidden = true;
    // Optional: tell your backend so it can start polling or wait for the webhook.
    fetch("/api/kyc/submitted", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ requestId }),
    });
  },
  onClose: ({ reason }) => {
    if (reason !== "completed") statusEl.textContent = "Verification was not finished.";
  },
  onError: ({ code, message }) => {
    statusEl.textContent = "Something went wrong. Please try again.";
    console.warn(code, message);
  },
});

button.addEventListener("click", async () => {
  button.disabled = true;
  statusEl.textContent = "";
  try {
    const r = await fetch("/api/kyc/start", { method: "POST" });
    if (!r.ok) throw new Error("start failed");
    const { onboardingUrl } = await r.json();
    VerifyMe.open({ url: onboardingUrl, mode: "modal" });
  } catch (e) {
    statusEl.textContent = "Could not start verification.";
  } finally {
    button.disabled = false;
  }
});

A runnable sandbox demo is available at /sdk-demo/ on your VerifyMe sandbox host: paste an onboardingUrl, try the four modes and watch the events live.