Add KYC to your product without building a KYC screen: verification links, an iframe and webhooks

Adewebs — Sun, 18 Oct 2026 22:39:40 +0000

Most teams that need to check who a customer is end up building the same thing: a page that asks for an ID number, a camera screen for a selfie, a progress bar, a consent notice, retries when a photo is blurry, and a back office to review the results. It is weeks of work, and it is not your product.

There is a shorter way: let a hosted flow do the screens, and keep control of the decision. Here is how that looks with the Verification Suite from IdentifyOrg (disclosure: I work on it). The ideas apply to any provider that offers hosted verification.

The three ways in

No code. A business sets up a flow in a dashboard (which checks, in what order), then sends each applicant a personal link on WhatsApp.
An iframe or a script on your own site.
Your server creates a session through the API for each applicant and reads the result afterwards.

All three end in the same place: a session with a status and a result per step.

Create a session from your server

curl -X POST https://api.identifyorg.com/v1/verification-sessions \
  -H "X-IdentifyOrg-Key: io_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "vf_YOUR_FLOW_ID",
    "reference": "order-1042",
    "applicant": { "name": "Ada Obi", "phone": "08031234567" }
  }'

You get back a url. Send it to the applicant, or give it to your page. Two details worth copying into your own designs:

reference is your id (an order or customer number). Sending the same reference again while that session is open returns the same session, so a retry never creates a second one.
Use a secret key on your server only. The flow id that goes in a public page is not a secret and cannot read anything.

Embed it

<div id="identifyorg-verify" data-flow="vf_YOUR_FLOW_ID"></div>
<script src="https://identifyorg.com/embed/verify.js" async></script>

Or a plain iframe. The one thing people forget is the permissions attribute, without which the browser will not let the frame use the camera:

<iframe
  src="https://identifyorg.com/v/vf_YOUR_FLOW_ID?embed=1"
  title="Identity verification"
  allow="camera; geolocation"
  style="width:100%;max-width:480px;height:760px;border:0"></iframe>

The form only renders inside websites you have allowed in the flow settings. Any other site sees a blank frame.

Listen to the frame

The embedded page talks to yours with postMessage. Always check the origin:

window.addEventListener("message", (e) => {
  if (e.origin !== "https://identifyorg.com") return;
  const d = e.data;
  if (!d || d.source !== "identifyorg-verify") return;

  if (d.type === "resize") iframe.style.height = d.height + "px";
  if (d.type === "completed") showThanks();   // they finished, not "they passed"
});

Events you will see: ready, started, step, received, resize, completed, error.

Do not treat completed as proof of anything. It only means the person reached the end. The result belongs to your server.

Read the result with a webhook

Register an endpoint and you get verification_session.started, .completed, .failed and .awaiting_funds. Verify the signature before you trust a payload. The header looks like t=1760437440,v1=9f2c... and the signature is an HMAC-SHA256 of "{t}.{raw_body}" with your webhook secret:

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, sig = parts["t"], parts["v1"]
    if abs(time.time() - int(t)) > tolerance:
        return False                      # too old: could be a replay
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

The payload includes the status, each step's outcome, and the ID number masked (last four digits). Pictures are never in the webhook; the business reviews those in the dashboard.

Test it first

A flow in test mode returns sample results, charges nothing and makes no real checks. Build the whole integration against it, then switch the flow to live. A test key does the same for the API.

What to decide yourself

A verification result is evidence, not a verdict. Decide what you require (an ID number check only, or also a selfie and a liveness test), what a "review" outcome means for your business, and who looks at it. The tool gives you the signals; the policy is yours.

Docs: Verification Suite and embed guide.

NIN vs BVN: what Nigerian identity numbers are, and which one to verify in your app

Adewebs — Sun, 18 Oct 2026 22:38:24 +0000

If you are building a product for Nigerian users, KYC conversations start with two eleven-digit numbers: the BVN and the NIN. They are not interchangeable, and picking the wrong one can exclude users or leave a gap in your checks.

BVN: Bank Verification Number

Issued through the banking system. You get one when you register biometrics with a bank.
It identifies a person across all their bank accounts.
Anyone with a bank account normally has one. Someone with no bank account normally does not.

Use it when you are dealing with money: lending, wallets, payouts, account opening. It ties the person to the banking system.

NIN: National Identification Number

Issued by the national identity authority (NIMC) to citizens and legal residents.
Not tied to a bank account. People without a bank account can have one.

Use it when you need to identify a person who may not be banked: staffing and HR, telecom and utility sign-ups, community programmes, resellers and agents.

Which should you ask for?

Your situation	Ask for
Lending or wallets for banked users	BVN
Onboarding sellers, riders, resellers or staff	NIN (or let the person choose)
High-risk accounts	Both, plus a selfie and liveness test
Unbanked users	NIN

Many products let the applicant pick either number, which avoids turning away someone who has only one.

What a number check does and does not prove

A lookup tells you the number exists and that the name (and other details you send) match the record. It does not prove that the person typing the number is the owner. Anyone who knows or has found a number can type it. To tie the number to a person you need more signals:

a selfie matched to the ID card photo the applicant uploads,
a liveness test so the selfie is a live person,
details that the genuine owner would know (date of birth and phone number are commonly required for a BVN check).

Also be clear about photos: some lookups return no photo, so there may be no official photo to compare a selfie with. If that is your provider's behaviour, tell your users and your compliance team, and compare with the card photo the applicant uploads instead.

Handle the data like a regulated identifier

These numbers are personal data under Nigerian data protection law. Practical habits:

Encrypt the number at rest and show only the last four digits by default.
Log every time someone reveals it.
Record consent with a timestamp and the version of the wording.
Delete data after the retention period you promised, and on request.
Tell users what you check and why.

Calling a verification API

With IdentifyOrg (where I work), a NIN check is one call, billed only when the check completes:

curl -X POST https://api.identifyorg.com/v1/verify/nin \
  -H "X-IdentifyOrg-Key: io_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "nin": "12345678901", "first_name": "Adaeze", "last_name": "Okafor" }'

Use a test key first: it returns realistic responses without charging or contacting any third party. If you do not want to build the screens yourself, the same checks (plus selfie match, liveness and address) are available as a no-code verification link you send on WhatsApp or embed on your site. More detail: NIN verification and BVN verification.

Identity numbers and the checks available depend on the country. Outside Nigeria, phone, ID card reading, selfie match, liveness and address checks work; identity-number checks for other countries are being added.

DEV Community: Adewebs