Documentation

Hosted Verification

The fastest way to add identity checks to your product: send your user's browser to a page we host, and get a signed result back at a URL of your choosing. You never see a raw NIN or BVN unless you explicitly fetch the full record afterward. No frontend code to write.

The flow, end to end

• 1. You redirect out. Send the browser to our hosted page with your client_key, which checks to run, and where to send them back.
• 2. Your user verifies. They enter their ID on our page. We run the check, debit your wallet, and build a signed result.
• 3. We redirect back. The browser lands on your redirect_url with the outcome and a signature appended as query parameters.
• 4. You verify the signature server-side before trusting the result, then let the user continue.

Step 1 — send the user to us

Redirect (a plain link or 302 works — no signing needed for this hop) to:

https://uverify.uselodger.com/verify/hosted
  ?client_key=ck_live_xxxx
  &checks[]=nin
  &checks[]=bvn
  &reference=order-42
  &redirect_url=https://yourapp.com/kyc/callback

Step 2 — the redirect back

Your redirect_url receives:

Step 3 — verify the signature

Recompute the signature over client_key|session_id|reference|outcome|verified_at using your api_secret, and compare it to sig with a constant-time comparison — never a plain === or ==, which leaks timing information an attacker can use to forge a valid signature byte-by-byte.

import crypto from "node:crypto";

function isValidCallback({ clientKey, apiSecret, sessionId, reference, outcome, verifiedAt, sig }) {
  const signingString = [clientKey, sessionId, reference, outcome, verifiedAt].join("|");
  const expected = crypto.createHmac("sha256", apiSecret).update(signingString).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(sig, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// In your callback route handler, reading the query string U-verify redirected back with:
const url = new URL(request.url);
const ok = isValidCallback({
  clientKey: process.env.VERIFYNG_CLIENT_KEY,
  apiSecret: process.env.VERIFYNG_API_SECRET,
  sessionId: url.searchParams.get("session_id"),
  reference: url.searchParams.get("reference"),
  outcome: url.searchParams.get("outcome"),
  verifiedAt: url.searchParams.get("verified_at"),
  sig: url.searchParams.get("sig"),
});

Fetch the full record

The redirect query string only carries the outcome — not the actual name, date of birth, address, or photo. Every production integration we've shipped fetches the full record from the backend as the very next step of the callback handler, before doing anything with the result. There are two ways to do this; pick based on what your callback route already has available.

Recommended — signed, no login required

Call this straight from your callback handler with the same client_key/api_secret pair you already use to sign every other request. No JWT, no prior login — just an HMAC over client_key|session_id, exactly like the callback signature above but with the session ID standing in for the full field list.

/hosted/result-by-reference is the same endpoint shape, keyed on the reference you originally passed in Step 1 instead of session_id (signed the same way, with reference in place of the session ID). Use it to build a "refresh verification status" action that re-checks a user's latest result on demand, without sending them through a fresh hosted redirect.

import crypto from "node:crypto";

async function fetchResultBySession(sessionId) {
  const clientKey = process.env.VERIFYNG_CLIENT_KEY;
  const apiSecret = process.env.VERIFYNG_API_SECRET;
  const sig = crypto.createHmac("sha256", apiSecret)
    .update(`${clientKey}|${sessionId}`)
    .digest("hex");

  const res = await fetch("https://api.uverify.uselodger.com/api/v1/hosted/result", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ client_key: clientKey, session_id: sessionId, sig }),
  });
  const body = await res.json();
  return body.success ? body.data : null; // data.checks.nin, data.outcome, ...
}

Alternative — from an authenticated admin session

If the code path already has a logged-in client JWT handy (an admin/staff panel reviewing a specific verification, for instance) and doesn't want to touch the raw api_secret, this does the same lookup under your existing session instead:

Session lifetime

• The session token from step 1 is single-use and expires after 30 minutes.
• Rate limits: 30/min on validate, 10/min on verify, per IP address.
• Treat an expired session as a normal "please try again" state, not an error worth alarming your user over.