kyc-flow — UI Prototype / Spec

Consent + resume

Identity (§1a)

Liveness — simple (§1b)

Liveness — sophisticated (§1b)

Face match (§1c)

Supporting (§1d)

Document (§7a)

Proof of address (§7b)

Vehicle (§8)

KYB (§1e)

Outcomes

—

Core decisions

👁

User view vs dev view. Scores, thresholds, SLAs, OCR confidence, provider names and raw reason codes are developer metrics — never shown to end users in production. The toggle in the toolbar flips them on. Library equivalent: <KycFlowProvider debug> + useKycDebug() hook. User-facing copy says "try again with better lighting", never "cosine 0.58 < 0.65".

✓

Consent is first-class. Every workflow has an OpenID scope expression. ConsentReceipt is stamped once, required before any instrument runs, and shown to the user with a per-scope breakdown — not a legal-text wall.

✓

Three buckets of verification: registry lookups (NIN / BVN / CAC — instant, server-side), biometric capture (liveness + face-match — on-device ML + server-side verification), and document upload (OCR + authenticity + fraud signals).

✓

The client never talks to Mono / IDRnd / Onfido / Jumio / Smile Identity directly. Every adapter posts to a host-configured verification backend which fans out to providers.

WhatsApp / email / phone support rows on every error + paused screen. NG market reality: WhatsApp is the support channel.

Awaiting external (key UX)

Long-wait verifications (field-agent 72h, manual review 48h, SCUML 1-5 days) are explicit machine state awaiting_external — not disguised as "loading". User is told plainly: "You're done for now, we'll email you."

Three resume modes — all host-opt-in: None (fire-and-forget, user never returns to the flow), cold resume (email link + initialSnapshot hydration), live push (useServerSync dispatches when the user happens to be on the page).

Tracking ref is always displayed with copy-to-clipboard. It's the one handle the user has for support follow-ups — don't hide it.

"Safe to close this page" is explicit copy. Users close tabs; the library stops all pollers on entry; the session lives in the backend.

Identity lookups

✓

NIN is show_instructions (form with 11-digit mask). BVN is redirect (OTP hosted by the verification backend — 3-step explainer tells the user what to expect before leaving the page).

BVN watch_listed: true routes to flagged with disposition manual_review — never auto-reject. Customer's cart/context stays intact.

Liveness + face match

✓

Simple tier: blink + smile + 5s clip. Sophisticated tier: head-turn + OTT speech + 15s video. Recording always on for audit — NDPA §30 consent receipt is stamped before capture.

✓

Quality gates (brightness, proximity, face-detection) run on-device. Simple tier skips on quality failure; sophisticated tier rejects.

Spoof detection (IDRnd codes) and cross-session HNSW identity-theft checks are security-toned outcome screens — brief, no defence details leaked, support escalation.

✓

Face-match has no UI during comparison — just a "Comparing…" spinner. Cosine threshold: 0.65 simple, 0.80 sophisticated, 0.75 cross-session alert.

Document verification

Document adapter is generic across providers + doc types — one @kyc-flow/adapter-document takes a documentType and routes to Smile Identity / Dojah / Onfido / Jumio server-side via baseUrl.

Passport has MRZ validation (ICAO 9303). Cards (DL / national ID / voter's card) require front + back. All doc types with a face photo optionally pair with a selfie for face-match.

Authenticity score ≥ 0.75 required. Tamper signals (edited PDF, reused template, altered fonts) raise flag — manual review, not auto-reject.

Proof of address

Freshness: document ≤ 90 days old. Stale docs fail with a clear copy recovery ("your bill from Jan is too old — upload your latest statement").

Name match against identity claims (Jaro-Winkler ≥ 0.85). Mismatch flags for manual review — may be a name change, nickname, or fraud.

PoA requires a prior identity source — the isAvailable gate checks for name claims in context.

Vehicle / transporter

Two input modes: lookup (plate or VIN → FRSC registry) or OCR (upload paper cert). Capture component offers both; adapter accepts either payload shape.

Ownership match against driver identity is a flag, not a reject. Leased, family-owned, or company-owned vehicles are common — route to manual review, not denial.

Driver onboarding verifies a person + N vehicles as nested subjects. Same machinery as KYB directors/UBOs; "Now verifying: Vehicle 2 of 3" breadcrumb.

KYB

Every KYB workflow must include CAC. Advanced CAC returns directors + shareholders, which expand into nested director_kyc sub-flows (one KYC run per director).

Per-director progress strip shows position + name + per-subject status. Critical UX — N-director onboardings can run 10+ minutes; the user needs to see where they are.

AML PEP / sanctions matches flag for manual review at ≥ 0.85 confidence. Never auto-approve. Sanctions hits specifically route to auto_reject_pending_escalation disposition.

Rejected vs flagged

Flagged ≠ rejected. Flagged = "under manual review, no decision yet". The user isn't blocked — they just wait for human adjudication. Copy and tone matter.

Rejected screens always offer a retry if retryable: true. Reason codes drive distinct copy (threshold_not_met vs document_stale vs mrz_invalid vs name_mismatch) so the user knows what to fix.

Before we start

step 1 of 4 · standard-kyc

What we'll verify

Consent declined

session cancelled

Verification cancelled

You didn't grant consent, so we won't verify your identity. You can come back anytime to restart the flow.

Welcome back

continuing from email link

Your verification is complete

Thanks for your patience. Our team reviewed your documents and verified everything. You can now continue onboarding.

Verified claims

NameAda Lovelace

NIN***-****-****

Address14 Bello St, Lagos

Enter your NIN

step 1 of 3 · identity

Your 11-digit National Identification Number. We verify it against NIMC through our verification backend.

NIN

11 digits · no spaces needed

Verifying NIN

talking to NIMC

Verifying…

This usually takes 3–5 seconds. We're checking your NIN against NIMC's registry.

NIN123 4567 8901

ProviderNIMC via backend

SLA≤ 5 seconds

Verify with your bank

BVN — 3 step process

You'll be redirected to your BVN page

We verify BVN via a secure 3-step flow. After you finish, you'll return here automatically.

We send an OTP to your BVN-linked phone

You enter the 6-digit code on our backend's secure page

You return here with a verified receipt — no manual data entry

Enter OTP

step 2 of 3 · BVN

6-digit code

Code sent to +234 ••• ••• 4321 (your BVN-linked number).

Expires in 14:28Resend code

Under review

BVN flagged

We need to review this

Your BVN matched a watchlist. This is not a rejection — our team will verify within 1 business day.

RefREV-8824

Quick face check

step 2 of 3 · liveness

😊

Hold still

You'll be asked to

Blink your eyes

Smile for the camera

Now smile

2 of 2 · hold steady

😊

SMILE

Challenges

✓

Blink your eyes

Smile — hold it

Quality (dev)

Brightness78

Face detection0.94

Proximity14 cm

Let's try again

capture quality was too low

🌑

TOO DIM

Issue detected (dev)

Brightness32 (min 60)

Face detection0.88

Proximity12 cm

We couldn't verify

capture check failed

Verification couldn't complete

Our check on your capture didn't pass. Please retry with your live face — not a screen or photo.

Slowly turn your head

enhanced liveness · 1 of 3

👤

TURN LEFT

Sweep progress

LEFT

RIGHT

95% path coverage required

Head angle-24°

Brightness82

Read this out loud

enhanced liveness · 2 of 3

Say this clearly

7 3 9 2 4 8

🎤

RECORDING

00:11 / 00:15

Analyzing

enhanced liveness · final step

Running security checks

Checking for deepfakes, cross-session matches, and consistency with your ID photo. Takes ~60 seconds.

✓

Spoof detection

✓

Transcription match

Cross-session HNSW search

Deepfake analysis

Face match

step 3 of 3

Comparing your selfie

Matching your capture against the photo on your NIN record. This usually takes about 3 seconds.

Cosine threshold≥ 0.65 (simple tier)

Comparing1 pair

SLA≤ 3 s

Face didn't match

below threshold

Face match below threshold

Your selfie didn't match the photo on your ID closely enough. This can happen when the ID photo is old or low-quality.

Cosine similarity0.58

Required≥ 0.65

Attempts left2 of 3

Security review required

protecting your identity

Your identity may be at risk

Your face matched another active verification session. We've paused this flow to protect you.

Incident refSEC-2904-X

Verify your phone

1 of 3 · supporting

Enter the 6-digit code we sent to +234 ••• ••• 8432.

Expires in 13:58Resend (3 left)

Wrong code

try again

That code didn't match. You have 2 attempts left before we lock this OTP.

Code didn't match. Double-check the SMS and try again.

Code expired

request a new one

Your code expired

OTP codes are valid for 15 minutes. Get a fresh one — we'll send it to the same number.

Choose an ID

document-kyc · 1 of 3

Pick a government-issued document. We accept any one of the following.

🛂

Passport

Data page — MRZ verified

🪪

Driver's licence

Front + back of card

🆔

National ID card

NIN card · front + back

🗳️

Voter's card (PVC)

Permanent voter's card

Capture passport data page

document-kyc · 2 of 3

P<NGAADELEKE<<OLUBUNMI<ADE<<<<<<<<
A12345678NGA7804233M3201154<<<<<<<<<<<<<<0

MRZ zone highlighted

Capture quality

Document detected✓

MRZ readable✓

Glare / blurnone

MRZ couldn't be validated

authenticity check failed

Something's off with your passport

We couldn't validate the MRZ (machine-readable zone). This may mean the photo is damaged, the passport is expired, or it's been tampered.

Expiry2024-03-11 (expired)

Check digitmismatch

Driver's licence

3 captures required

Step 1 of 3 — FRONT

🪪

dl_front.jpg

OCR complete · class C · expires 2028

✓

Step 2 of 3 — BACK

🪪

dl_back.jpg

Barcode decoded · state Lagos

✓

Step 3 of 3 — SELFIE

Take a selfie

We match your face to the DL photo

Under review

document flagged

Your document is being reviewed

The automatic authenticity check couldn't confirm your document with high confidence. A reviewer will check manually within 24 hours.

Authenticity score0.68 (threshold 0.75)

Tamper score0.09 (OK)

Review SLA≤ 24 hours

RefDOC-44-2019

Proof of address

document must be ≤ 90 days old

Pick one. Upload a clear photo or PDF.

💡

Utility bill

Electricity, water, gas, internet

🏦

Bank statement

Header showing name + address

📄

Tax notice

FIRS, LIRS, other govt authority

✉️

Government letter

Addressed to you, last 90 days

Upload utility bill

≤ 90 days old

Drag or tap to upload

JPG / PNG / PDF · up to 10 MB

📄

ikeja_electric_march_2026.pdf

Issued 2026-03-14 · 32 days old · checking…

Document too old

please upload a newer one

Your bill from January is too old

We only accept documents issued within the last 90 days. Please upload your latest utility bill or bank statement.

Document date2025-01-04

Age108 days (max 90)

Under review

name on document flagged

Name on document doesn't quite match

The name on your bill ("Ada B. Lovelace") doesn't closely match your identity ("Ada Lovelace"). This is often a valid difference — a reviewer will check within 24 hours.

Name on docAda B. Lovelace

Verified nameAda Lovelace

Match score0.78 (threshold 0.85)

RefPOA-0844

Document flagged

sent for manual review

We noticed something unusual

Our automatic check spotted signs the document may have been modified. A reviewer will verify the original within 24–48 hours.

RefPOA-TMPR-12

Your vehicle

driver onboarding · vehicle 1 of 1

Enter your plate number or VIN. We look it up in the FRSC registry and match it to your identity.

Plate number

VIN (17 chars)

Upload RC

OCR + plate cross-check

Upload your RC certificate

Photo or scan · JPG / PNG / PDF

🚗

rc_cert.jpg

OCR: Plate LND-347-KL · Toyota Camry 2019

Verified via FRSC

LND-347-KL

OwnerAda Lovelace

Make / modelToyota Camry 2019

RC expiry2027-08-14

Photograph your plate

cross-check against RC

LND-347-KL

Plate detected✓

OCR confidence0.96

Matches RC✓ LND-347-KL

Review needed

vehicle ownership mismatch

Registered owner doesn't match your name

The vehicle is registered to a different person. That's OK if it's leased or a family member's — we'll just review manually within 24 hours.

Registered ownerAdebayo J. Ogundimu

Driver (you)Ada Lovelace

Name match0.12

Verify your business

standard-kyb · step 1 of 5

Enter your Corporate Affairs Commission registration number. We look it up + fetch your directors and shareholders.

RC / BN number

From your CAC certificate

Bunmi Trading Co. Ltd.

RC4829110 · active · 3 directors

Business verified

Next, each director completes their own KYC. Takes about 2 minutes each.

3 directors

Adebunmi Lawal

Ready

Chidi Okafor

Ready

Temitope Akinola

Ready

Verifying directors

2 of 3 — Chidi Okafor

Directors

Adebunmi Lawal

✓ Verified

Chidi Okafor

In progress

Temitope Akinola

Pending

AML review

1 match found · manual review

One director matched a PEP list

Our compliance team will review the match manually. This isn't a rejection — politically exposed persons can legitimately be directors.

DirectorAdebunmi Lawal

Match listPEP (domestic)

Confidence0.92

SourceComplyAdvantage

RefAML-4425

Identity verified

all 3 steps passed

You're all set

Your identity is verified. You can continue to the app.

Verified claims

NameAda Lovelace

DOB1815-12-10

NIN***-****-****

Face-match score0.87

Under review

not rejected

We need a moment

Your verification matched a rule that requires a human reviewer. We'll email you within 24 hours.

RefREV-7234

Couldn't verify

we weren't able to confirm your identity

We couldn't verify your identity

Face match fell below our required threshold. You can try again with better lighting, or use a different ID document.

Reasonface_match_below_threshold

Score0.58 / 0.65

Just a moment

processing your capture

Final processing

Your capture is being analysed on our servers. This usually finishes in about a minute. Please keep this page open.

Elapsed23s

Expected≤ 60s

We'll take it from here

field-agent visit · 72 hours

You're done for now

A verification officer will visit your declared address to confirm. You don't need to stay on this page — we'll email you when it's complete.

RefVIS-2018-443

~72:00:00

Expected turnaround

Session expired

consent / session timed out

This session timed out

Your verification took longer than our security window allows. Your progress wasn't saved — please restart from the beginning.

Session refKYC-2026-0411-ABC

Expiredconsent (90 min)

Cancelled

verification not completed

Verification cancelled

You cancelled the flow before it finished. You can start again anytime.

Security review required

please contact support

We need to verify in person

Our checks flagged something on your capture that we need a human to review. Don't retry — please reach out so our team can help directly.

RefSEC-1992