Design eKYC identity verification

A KYC journey takes minutes to days: the user drops off after PAN and returns tomorrow on another phone, DigiLocker consent happens in a browser redirect, a reviewer decides after hours, a vendor is down for 20 minutes. A request-response design with a status column and cron jobs ends with many half-finished states and nobody sure which checks ran. A durable execution engine such as Temporal makes the whole journey one piece of code whose progress is persisted: each verification is an activity with its own retry policy and timeout; user actions and reviewer decisions arrive as signals; waits ('wait 48 h for review, remind at 24 h') are durable timers that survive restarts. Rules from the guide apply: workflow code must be deterministic (no clock or network calls directly), activities must be idempotent because they will be retried, and large payloads such as images stay in S3 with only references in workflow history. Use workflow_id = application_id so a second start returns the running workflow. Version workflow code carefully, since thousands of applications are mid-flight during every deploy.

This system holds the most sensitive data a company has, so design for breach containment. Aadhaar numbers, where you are permitted to collect them at all, must be stored only in an Aadhaar Data Vault: a separate, encrypted store with keys in an HSM, accessed through one service that returns a reference token. Everything else (applications, logs, analytics, reviewer screens) sees the token and the last four digits. DigiLocker or offline eKYC XML is digitally signed by UIDAI, so verify the signature instead of trusting the payload. Encrypt documents in S3 with KMS keys, restrict decryption to the services and roles that need it, and keep all data in Indian regions. Apply PII redaction in logging middleware and in any prompt sent to an LLM. The Digital Personal Data Protection Act requires purpose-limited use and deletion when no longer needed, while PMLA rules require KYC records for five years after the relationship ends, so retention is a policy per field, enforced by lifecycle rules, not ad hoc deletes. Every PII read writes an audit event with actor and reason.

Each check returns a normalised result: pass, fail or a score with reasons. A rules engine (versioned config, not code scattered across services) combines them: auto-approve when PAN is valid and linked, Aadhaar signature verified, liveness above 0.9, face match above 0.85, name match above 0.85 and screening clear; auto-reject on hard failures such as a PAN that does not exist; everything else goes to review. Thresholds are tuned with data: track false approvals found by audits and the review rate, since every 1% more review costs thousands of reviewer hours on IPO day. AI helps in three places: document extraction for unstructured address proofs, liveness and face matching (from specialised vendors), and drafting review summaries. Keep it out of the final decision path: an LLM reading a document can be prompt-injected by text printed on that document, and its output varies. Use structured extraction with field-level confidence, cross-check extracted values against authoritative sources (PAN database, signed XML), and send low-confidence results (below 0.9) to humans. Record the model and prompt version used in the verification result for audit.

Most of the system's latency, cost and failures come from outside: PAN verification partners, DigiLocker, CKYC, KRAs, penny-drop banks, liveness vendors and screening lists. Every call goes through an activity that first checks verification_results for the same idempotency key (application_id + check_type + input hash) and returns the stored result if present, so a retry after a timeout or a user re-submitting the same PAN does not pay twice. Where vendors support client reference ids, pass them so the vendor can dedupe too. Wrap each vendor with timeouts, a circuit breaker and a per-vendor token bucket sized to its contracted rate limit. Keep a second vendor for critical checks (face match, penny drop) and route by health; normalise responses behind one internal interface so switching is configuration. On IPO day, queue onboarding work instead of hammering vendors: the workflow simply waits for capacity, and the app shows progress and notifies the user when done. Many vendor results arrive by callback, so the incoming webhook design (verify, store, signal the workflow) is reused here.

Temporal gives retries, timers, signals and visibility out of the box, but adds a cluster to run and a programming model to learn. A Postgres state machine with an outbox and job queue is simpler for 4-5 steps. With many vendors, human review and multi-day waits, the durable engine pays for itself.

DigiLocker returns signed documents with user consent and is widely used by brokers and lenders. OTP eKYC through a licensed KUA partner is fast but RBI limits what accounts opened with OTP-based eKYC alone can do until full KYC is completed. Support more than one path so an outage in one does not stop onboarding.

Higher thresholds reduce fraud but send more people to manual review, raising cost and drop-off. Lower thresholds speed up onboarding but risk regulatory findings. Tune with measured false-approve and review rates, and use stricter thresholds for high-risk segments.

Showing each result instantly feels good but ties UX to vendor latency. Do the fast checks synchronously (PAN in ~1 s) and let slow ones finish async with a push notification.

Contracted TPS caps throughput, not our servers. Negotiate burst capacity before known events, multi-vendor routing, and a durable queue so excess users wait rather than fail.

35k cases in a day can overwhelm the team. Prioritise by risk and customer value, auto-resolve common patterns (initials vs full name) with better matching, and add temporary reviewers with scoped access.

Storing images or large XML in workflow history slows replays. Keep only S3 references and small normalised results in history.

Offer an alternative path (Aadhaar OTP eKYC via partner, or CKYC reuse). Users already in the DigiLocker step get a 'try again later' with a notification when it recovers.

Temporal reschedules the activity; the idempotency check returns the stored vendor result if the call had completed, so there is no duplicate charge or duplicate penny drop.

Steps that need to store or read raw identifiers pause and retry; nothing writes raw PII elsewhere as a shortcut. Onboarding slows but data protection is never relaxed.

Rules are versioned and every decision records the rule version, so affected applications can be found and re-evaluated. Roll out rule changes as a shadow evaluation first.