Building a White-Label KYC System from Scratch Part 1: Why I Built This

Frank Mwangi | Software engineer | Fintech @dadanada| RegTech | eKYC @intact-io.com @id.intact-io.com

A 4-part series on building Intact ID, a production-grade identity verification platform

BUSINESS: ***intact-io.com INTACT ID: [id.intact-io.com](http://id.intact-io.com/)* CONTACTS**: contact@intact-io.com

The Internship That Changed Things

Last year I did an internship at a fintech company . I won’t pretend it was glamorous at first it was intense, the codebase was large, and the engineers around me had clearly been thinking about problems I hadn’t even noticed yet.

But that was the point.

I watched how they handled identity verification — how seriously they took it, the edge cases they accounted for, the compliance requirements that shaped every design decision. KYC (Know Your Customer) wasn’t just a checkbox for them. It was infrastructure. It was trust. It was the thing standing between their product and fraud.

By the time the internship ended, I knew I wanted to build something real. Not a tutorial project. Not a CRUD app. Something that would force me to think the way those engineers thought.

So I decided to build a white-label KYC system.

What Is KYC, and Why Does It Matter?

If you’ve ever opened a bank account, applied for a loan, or signed up for a crypto exchange, you’ve gone through KYC. It’s the process by which a company verifies that you are who you say you are.

In practice, this means:

• Submitting a government-issued ID (national ID, passport, driver’s licence)
• Taking a selfie so your face can be matched against the ID
• Sometimes providing proof of address or going through a background check

For regulated industries banking, lending, crypto, insurance this isn’t optional. Regulators require it. And the companies that get it wrong face serious consequences: fines, licence revocations, reputational damage.

The problem is that building KYC properly is hard. It involves computer vision, OCR, document parsing, liveness detection, sanctions screening, webhook systems, billing, and a whole compliance layer on top. Most startups either buy an expensive third-party solution (Smile ID, Jumio, Onfido) or cobble something together that breaks under edge cases.

I wanted to understand what it actually takes to build this from the ground up.

The Goal: A White-Label Platform

id.intact-io.com

Intact ID is designed as a platform that other companies can plug into. Think of it like Stripe for identity verification a company signs up, gets API keys, and starts submitting verifications through our API. We handle the AI, the document parsing, the compliance logic, and the webhooks. They just get a result back.

The system supports three verification tiers:

Tier 1 — Basic: Face match + liveness check + OCR field extraction. Fast, lightweight, covers most use cases.

Tier 2 — Standard: Everything in Tier 1, plus a cross-check against the government identity database (IPRS in Kenya). Confirms the ID number actually exists and the name matches.

Tier 3 — Enhanced: Everything in Tier 2, plus sanctions screening against OFAC, UN, and EU lists. Required for high-risk financial products.

Companies can choose which tier suits their risk appetite and regulatory requirements.

The Architecture at a Glance

The system is built as a set of microservices, each responsible for one thing:

Auth Server (Java / Spring Boot) — the brain of the operation. Handles company onboarding, API key management, verification orchestration, webhooks, billing, and the admin dashboard backend.

Face Screening Service (Python / FastAPI / DeepFace) — takes a selfie and an ID photo, runs face verification using ArcFace, checks for liveness and anti-spoofing.

OCR Service (Python / FastAPI / PaddleOCR) — takes a document image, extracts structured fields (name, date of birth, ID number, nationality), handles multiple document types across multiple countries.

IPRS Service — connects to the Kenyan government identity database for Tier 2 verification.

Sanctions Service — screens against international sanctions lists for Tier 3 verification.

Each service is independently deployable, communicates over HTTP, and is secured with API keys. The auth server orchestrates everything.

Why Microservices?

I want to be honest here: microservices add complexity. There is a version of this project that could live in a single Spring Boot application and be perfectly fine for an early-stage product.

But there were real reasons to separate things:

The ML services need Python. DeepFace, PaddleOCR, and the models they depend on live in the Python ecosystem. There’s no good equivalent in Java. Trying to force ML inference into a JVM process would have been painful.

The face and OCR services are independently scalable. A verification that needs to process 10 documents doesn’t need more auth server instances — it needs more OCR capacity. Keeping them separate means you can scale each one to match its actual load.

Python 3.10 exactly. PaddlePaddle (the framework PaddleOCR runs on) is incompatible with Python 3.11+. Isolating this in its own container means that constraint doesn’t infect anything else.

These weren’t premature architectural decisions — they were shaped by the actual constraints of the tools.

What’s Coming in the Rest of the Series

This series is four parts:

Part 1 (this post): Why I built this, what KYC is, and the high-level architecture.

Part 2 — Auth + Company Onboarding: How the auth server works, the 4-eye approval workflow for onboarding new companies, API key management with dev/prod environments, JWT + API key security filters, and the billing system.

Part 3 — Face Verification + OCR Pipeline: How the face service uses DeepFace and ArcFace to match faces with sub-second latency, how the OCR service parses identity documents across multiple countries using MRZ parsing and label-based extraction, and the decisions that shaped both.

Part 4 — The Full System: Putting it all together — the KYC verification flow end to end, webhook delivery with retry logic, what’s still being built (IPRS, sanctions screening), and what I’d do differently.

A Note Before We Go Further

This project isn’t finished. IPRS integration and sanctions screening are still in progress. The production checklist has items still unchecked.

I’m writing this series as I build, not after. That means some decisions are still being made, some things will change between posts, and I’ll be honest about what’s working and what isn’t.

That’s intentional. The most useful engineering writing I’ve read doesn’t just describe the finished system it describes the thinking behind it, including the wrong turns.

Let’s build.

Next: Part 2 — Auth Server, Company Onboarding, and the 4-Eye Approval Workflow