Node.js

# .env (server only)
AUTHENTICA_BASE_URL=https://authentica-merge-integration.t2.sa
AUTHENTICA_CLIENT_ID=YOUR_CLIENT_ID
AUTHENTICA_CLIENT_SECRET=YOUR_CLIENT_SECRET
AUTHENTICA_RETURN_URL=https://yourapp.com/verify/done

// config.js
export const authentica = {
  baseUrl: process.env.AUTHENTICA_BASE_URL,
  clientId: process.env.AUTHENTICA_CLIENT_ID,
  secret: process.env.AUTHENTICA_CLIENT_SECRET,
  returnUrl: process.env.AUTHENTICA_RETURN_URL,
};

export function basicHeader() {
  const token = Buffer.from(
    `${authentica.clientId}:${authentica.secret}`
  ).toString("base64");
  return `Basic ${token}`;
}

import express from "express";
import crypto from "crypto";
import { authentica, basicHeader } from "./config.js";

const app = express();

// Pending actions, keyed by state. Use your database if the action can outlive the process.
const pendingByState = new Map();

app.post("/verify/start", express.json(), async (req, res) => {
  // 1) YOUR checks for this action (password, balance, permissions, ownership …)
  const userRef = "user-123";            // stable id — same value every time
  const channel = "sms";                 // SMS-only — set on the server
  const operationSensitivity = "normal"; // your backend decides; "sensitive" forces OTP
  const state = crypto.randomUUID();     // opaque, single use, carries no meaning

  const r = await fetch(`${authentica.baseUrl}/api/V1/Verify/session`, {
    method: "POST",
    headers: {
      Authorization: basicHeader(),
      "Content-Type": "application/json",
      // A timeout retry must not text the user twice.
      "Idempotency-Key": state,
    },
    body: JSON.stringify({
      userRef,
      destination: req.body.destination,   // phone number
      channel,
      state,
      returnUrl: authentica.returnUrl,
      operationSensitivity,
    }),
  });

  const body = await r.json();
  if (!body.isSuccess || !body.result?.verifyUrl || !body.result?.handoff) {
    return res.status(502).json({ error: body.errorCode || "session_failed" });
  }

  // Remember WHAT is being verified, WHO for, and the sessionId you read the outcome with.
  pendingByState.set(state, {
    userRef,
    sessionId: body.result.sessionId,
    action: req.body.action,       // "login" | "payment" | "phone-change" | …
    params: req.body.params,       // e.g. { paymentId: 8842 }
    done: false,
  });

  // Both values go to the browser: it POSTs `handoff` to `verifyUrl` as the `hx` field.
  // `handoff` is single-use with a 120 s TTL — never put it in a URL.
  res.json({ verifyUrl: body.result.verifyUrl, handoff: body.result.handoff });
});

async function getSessionStatus(sessionId) {
  if (!sessionId) return null;
  const r = await fetch(
    `${authentica.baseUrl}/api/V1/Verify/session/${encodeURIComponent(sessionId)}`,
    { headers: { Authorization: basicHeader() } },
  );
  const body = await r.json();
  return body.isSuccess ? body.result : null;   // { status, userRef, state, method, completedAt }
}

// Idempotent fulfilment — safe to run twice. Called from the landing route AND the sweep.
function onVerified(state, pending) {
  if (pending.done) return;
  pending.done = true;
  pendingByState.set(state, pending);
  // "login" -> sign them in; "payment" -> capture pending.params.paymentId; …
}

app.get("/verify/done", async (req, res) => {
  const { session_id: sessionId, state } = req.query;   // neither is a credential

  // 1) Resolve YOUR pending record.
  const pending = state ? pendingByState.get(state) : null;
  if (!pending) return res.redirect(303, "/verify/failed");
  if (pending.done) return res.redirect(303, "/verify/success");   // a refresh

  // 2) Ask Authentica. Use the sessionId from YOUR record, not the URL.
  const status = await getSessionStatus(pending.sessionId || sessionId);

  // 3) Three things must agree: verified, our state, our user.
  if (
    !status ||
    status.status !== "verified" ||
    status.state !== state ||
    status.userRef !== pending.userRef
  ) {
    return res.redirect(303, "/verify/failed");
  }

  // 4) Fulfil once, then set YOUR OWN session — that is the point of the flow.
  onVerified(state, pending);
  req.session.userId = pending.userRef;          // your own auth
  return res.redirect(303, "/verify/success");
});

setInterval(async () => {
  for (const [state, p] of pendingByState) {
    if (p.done) continue;
    const status = await getSessionStatus(p.sessionId);
    if (status?.status === "verified" && status.userRef === p.userRef) onVerified(state, p);
  }
}, 60_000);

const { verifyUrl, handoff } = await fetch("/verify/start", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  credentials: "include",
  body: JSON.stringify({
    action: "payment",
    params: { paymentId: 8842 },
    destination: "0501234567",
  }),
}).then((r) => r.json());

// POST into the hosted page — never navigate to verifyUrl.
const f = document.createElement("form");
f.method = "POST";
f.action = verifyUrl;                 // as returned — do not append anything
f.style.display = "none";
const i = document.createElement("input");
i.type = "hidden";
i.name = "hx";
i.value = handoff;
f.appendChild(i);
document.body.appendChild(f);
f.submit();