Add age verification to your website

// YOUR SERVER: implement POST /api/age-check/start on your website.
// Framework-neutral example, not a ready-made server or SDK package.
// merchant.* are REQUIRED adapters for your own auth, CSRF, rate limits and database.
const VERIFICATION_BASE = "https://YOUR_ID_BEFORE_ENTRY_HOST";
const SECRET_KEY = process.env.ID_BEFORE_ENTRY_SECRET_KEY;
const RETURN_URL = "https://YOUR-WEBSITE.example/age-check/return";

async function startAgeCheck(request) {
  const customer = await merchant.requireCustomer(request);
  await merchant.requireCsrf(request);
  const { flow } = await request.json();
  if (flow !== "popup" && flow !== "redirect") {
    return Response.json({ error: "invalid_flow" }, { status: 400 });
  }

  // This adapter MUST serialize starts for this customer and stop duplicates.
  // A repeated POST to the provider can create another session and spend another credit.
  return merchant.withStartGuard(customer.id, async () => {
    const reference = String(customer.id); // Derived from your authenticated server context.
    if (!reference || reference.length > 200) throw new Error("Invalid customer reference");
    if (!SECRET_KEY) throw new Error("Missing server configuration");

    const response = await fetch(VERIFICATION_BASE + "/api/public/v1/sessions", {
      method: "POST",
      headers: {
        Authorization: "Bearer " + SECRET_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        reference,
        ...(flow === "redirect" ? { return_url: RETURN_URL } : {}),
      }),
      cache: "no-store",
    });
    const session = await response.json();
    if (!response.ok) {
      // Map the provider code to your own safe error UI; do not log the whole response.
      return Response.json(
        { error: session.error?.code || "verification_unavailable" },
        { status: response.status, headers: { "Cache-Control": "no-store" } },
      );
    }
    if (!session.id || !session.client_token || !session.url) {
      throw new Error("Unexpected create-session response");
    }

    // DURABLY bind before returning credentials or redirecting the customer.
    // Save which provider site/key belongs to this binding if you manage several sites.
    await merchant.verifications.saveCurrent({
      customerId: customer.id,
      sessionId: session.id,
      reference,
      expiresAt: session.expires_at,
    });

    return Response.json(
      { id: session.id, client_token: session.client_token, url: session.url },
      { headers: { "Cache-Control": "no-store" } },
    );
  });
}

<!-- YOUR WEBSITE. Set the CSRF meta value using your server's CSRF system. -->
<meta name="csrf-token" content="RENDER_YOUR_CUSTOMER_CSRF_TOKEN_HERE">
<button id="verify-age" type="button">Verify my age</button>
<p id="age-check-message" role="status"></p>
<script>
  const button = document.getElementById("verify-age");
  const message = document.getElementById("age-check-message");
  let sdkPromise;

  function loadAgeCheckSdk() {
    if (window.IDBeforeEntry?.__loaded) return Promise.resolve();
    if (!sdkPromise) {
      sdkPromise = new Promise((resolve, reject) => {
        const script = document.createElement("script");
        script.src = "https://YOUR_ID_BEFORE_ENTRY_HOST/widget.js";
        script.onload = () => window.IDBeforeEntry?.__loaded
          ? resolve() : reject(new Error("The age-check script did not initialise"));
        script.onerror = () => reject(new Error("The age-check script could not load"));
        document.head.appendChild(script);
      }).catch((error) => { sdkPromise = undefined; throw error; });
    }
    return sdkPromise;
  }

  async function merchantPost(path, body) {
    const response = await fetch(path, {
      method: "POST",
      credentials: "same-origin",
      headers: {
        "Content-Type": "application/json",
        "X-CSRF-Token": document.querySelector('meta[name="csrf-token"]').content,
      },
      body: JSON.stringify(body),
    });
    if (!response.ok) throw new Error("Your website could not complete the request");
    return response.json();
  }

  button.addEventListener("click", async () => {
    button.disabled = true;
    message.textContent = "Opening your age check…";
    try {
      await loadAgeCheckSdk(); // Load before creating a chargeable session.
      const session = await merchantPost("/api/age-check/start", { flow: "popup" });
      await IDBeforeEntry.verify({
        siteKey: "pk_REPLACE_WITH_YOUR_24_CHARACTER_PUBLIC_KEY",
        session: { id: session.id, token: session.client_token },
        onError: () => {
          message.textContent = "The age check could not open. Please try again later.";
          IDBeforeEntry.close(); // UI close only; not a server cancellation.
        },
      });

      // The promise resolves on close. Browser results are NOT proof of verification.
      // Your server reads its own stored session ID, not an ID chosen by this browser.
      const result = await merchantPost("/api/age-check/confirm", {});
      message.textContent = result.verified === true
        ? "Age check confirmed. You can continue."
        : result.status === "pending"
          ? "This check is not complete. Please try again or contact the website."
          : "This check did not pass. Please follow the website's next steps.";
      // Your server must also enforce verification on any protected action or page.
    } catch {
      message.textContent = "We could not complete the check. Please try again later.";
    } finally {
      button.disabled = false;
    }
  });
</script>

<!-- YOUR WEBSITE. No browser SDK is needed for a hosted redirect. -->
<!-- Sessions are created by your server using https://YOUR_ID_BEFORE_ENTRY_HOST/api/public/v1/sessions. -->
<meta name="csrf-token" content="RENDER_YOUR_CUSTOMER_CSRF_TOKEN_HERE">
<button id="start-age-check" type="button">Verify my age</button>
<p id="age-check-message" role="status"></p>
<script>
  async function merchantPost(path, body) {
    const response = await fetch(path, {
      method: "POST",
      credentials: "same-origin",
      headers: {
        "Content-Type": "application/json",
        "X-CSRF-Token": document.querySelector('meta[name="csrf-token"]').content,
      },
      body: JSON.stringify(body),
    });
    if (!response.ok) throw new Error("Your website could not complete the request");
    return response.json();
  }

  document.getElementById("start-age-check").addEventListener("click", async (event) => {
    const button = event.currentTarget;
    button.disabled = true;
    try {
      const session = await merchantPost("/api/age-check/start", { flow: "redirect" });
      window.location.assign(session.url); // Use the API URL unchanged.
    } catch {
      document.getElementById("age-check-message").textContent =
        "The age check could not start. Please try again later.";
      button.disabled = false;
    }
  });

  // ON YOUR RETURN PAGE, after the customer returns and auth is restored:
  // Run this in that page's own script, not immediately on the start page.
  async function confirmReturnedAgeCheck() {
    const params = new URLSearchParams(window.location.search);
    const result = await merchantPost("/api/age-check/confirm", {
      returnedSessionId: params.get("carded_session"),
    });
    // carded_status and carded_reason are untrusted hints. Never use them to grant access.
    // Only the server-confirmed response can update this page's UI.
    document.getElementById("age-check-message").textContent = result.verified === true
      ? "Age check confirmed. You can continue."
      : "Your age check has not passed. Follow the website's next steps.";
  }
  // Your return page calls confirmReturnedAgeCheck().catch(showYourRecoveryMessage).
  // A closed browser tab or abandoned check may never visit the return page.
</script>

// YOUR SERVER: implement POST /api/age-check/confirm on your website.
// merchant.* are REQUIRED adapters for your auth, CSRF and database.
const VERIFICATION_BASE = "https://YOUR_ID_BEFORE_ENTRY_HOST";
const SECRET_KEY = process.env.ID_BEFORE_ENTRY_SECRET_KEY;

async function confirmAgeCheck(request) {
  const customer = await merchant.requireCustomer(request);
  await merchant.requireCsrf(request);
  const input = await request.json();
  const binding = await merchant.verifications.currentFor(customer.id);
  if (!binding) return Response.json({ error: "no_bound_check" }, { status: 404 });

  // The redirect query is a hint to compare, never the ID to fetch from the provider.
  if (input.returnedSessionId != null && input.returnedSessionId !== binding.sessionId) {
    return Response.json({ error: "check_mismatch" }, { status: 403 });
  }
  if (!SECRET_KEY) throw new Error("Missing server configuration");
  const response = await fetch(
    VERIFICATION_BASE + "/api/public/v1/sessions/" + encodeURIComponent(binding.sessionId),
    {
      headers: { Authorization: "Bearer " + SECRET_KEY },
      cache: "no-store",
    },
  );
  if (!response.ok) {
    // Fail closed. Show a retry/support message; do not mark the customer as verified.
    return Response.json(
      { error: "verification_unavailable" },
      { status: 503, headers: { "Cache-Control": "no-store" } },
    );
  }
  const session = await response.json();
  if (session.id !== binding.sessionId || session.reference !== binding.reference) {
    return Response.json({ error: "check_mismatch" }, { status: 403 });
  }

  const verified = session.status === "passed" && session.passed === true;
  if (verified) {
    // Atomic + idempotent: re-check that this binding is still current for this customer.
    // Store the provider session ID and verified outcome against this exact customer.
    const saved = await merchant.verifications.confirmIfCurrent(customer.id, binding.sessionId);
    if (!saved) return Response.json({ error: "check_changed" }, { status: 409 });
  }
  return Response.json(
    { verified, status: session.status, reason: session.reason },
    { headers: { "Cache-Control": "no-store" } },
  );
}
// pending: keep access locked; confirm again later with bounded polling/backoff.
// failed: keep access locked and present the reason/next step.
// cancelled or expired: keep access locked; offer an explicit new attempt when appropriate.
// Network errors, unknown statuses and malformed responses must never grant access.
// Do not forward the entire provider payload: face_photo may contain a customer's photo.