Customer and CDD
Know the customer, and be able to prove how you know
A customer record here is not a form that was filled in. It is an identity evidence set, an ownership chain, a risk assessment with its factors visible, and a lifecycle of decisions each bound to the person who made it. Front office captures; nobody approves their own work.
Identifier capture and CBN tier requirements are enforced in the shipped build. Electronic verification against NIBSS, NIMC or the Corporate Affairs Commission requires a provider adapter that has not been built — the platform records the identifier as unverified rather than asserting a check nobody ran.
The problem
Most CDD failures are evidence failures, not capture failures
Institutions rarely fail an examination because a field was empty. They fail because the record cannot answer a follow-up question: who verified this, against what, on what date, and what did the risk model actually say at the moment the account was opened.
A tier that was never earned
CBN tiering turns on identity evidence, not on an operator's judgement. A Tier 2 account opened against an unverified BVN is a control failure that only surfaces when someone reconstructs the file — usually during an examination, usually across thousands of accounts at once.Ownership that stops at the first layer
A corporate customer's declared director list is not its beneficial ownership. Without a validated chain — and without the historic edges kept when it changes — the institution cannot show who controlled the entity on the date of the transaction it is being asked about.A risk rating with no reconstruction
A score in a column is not a risk assessment. If nobody can retrieve which factors, weights and bands produced it, or which model version was active that day, the rating cannot support the decision that was taken on the strength of it.
How it works
Capture, evidence, assess, decide — with the roles kept apart
The sequence below is enforced by permissions and workflow state rather than by convention. Front office can capture and submit but cannot review its own application; review and decision are separate rights again; and an approval is refused outright while identity requirements are outstanding.
Compliance administrator
The CDD form is configuration, not a code change
Fields, required-ness and conditional sections are defined by a governed JSON Schema, and every key must resolve to a known storage binding — a form that asks for something the data model has nowhere to put fails validation before it can be proposed, rather than silently discarding the answer. Changes go through propose, validate, approve, activate, and old versions are retained so a record made under a previous form is still readable under the form that governed it.Front office
Capture the party, the address and the identifiers
Individual and corporate customers, an external reference, a classification and a KYC tier, assigned to an organisational unit. Nigerian addresses are selected from an embedded 774-location dataset of states, LGAs and FCT area councils with the state/LGA combination validated and the canonical codes stored; non-Nigerian addresses use bounded structured fields, and an unknown or private-use country code is rejected rather than stored. Supported identifier schemes are BVN, NIN, CAC, TIN, SCUML, passport, driver’s licence and voter’s card.Platform
Identifiers are encrypted, and searchable anyway
Each identifier is encrypted under a data-encryption key belonging to that data subject, and indexed with an HMAC blind index keyed by the tenant’s key. Equality search — “does this BVN already exist here?” — works without decrypting anything, and the index is not comparable across tenants, so it cannot be used to correlate a person between two institutions running on the same installation. Revealing a stored identifier is a separate, MLRO-level permission and writes a sensitive-access audit record.Front office and compliance
Declare the ownership chain, then verify it separately
Direct and nested ownership and control relationships are declared with a bounded owner count, and each target is validated against the subject’s reachable chain so a cycle or a cross-tenant reference is refused transactionally. Verification is recorded independently of declaration — capturing an owner never implies anyone checked. When ownership changes after activation the replacement runs through an encrypted maker-checker preview and apply, historic edges are closed rather than deleted, and a material change invalidates the prior verification instead of inheriting it. The percentage the screen shows against each owner is the effective stake through the whole chain, resolved to a bounded depth, because that — not the direct holding — is what decides beneficial ownership.Compliance
Ownership verification is a recorded human act, and says so
Verification is recorded against a closed list of methods — a board resolution with identification, a CAC status report, or a certified UBO register — together with the evidence reference an examiner will read back. Nothing in the platform checks that report: the CAC register adapter does not exist, so this is an attestation by a named person at a recorded time, which is exactly what it is labelled as rather than being dressed up as an automated check.Platform
Documents are encrypted before they reach storage, and written once
Identity and CDD document bytes are encrypted under the subject key, and so are the original filenames — an object key contains only tenant and attachment identifiers, so a customer name or a filename never appears in a URL or in the object namespace. The evidence store has no application delete operation: filesystem writes commit with an atomic hard link and S3 writes use a conditional put, so an existing key is an error, never an overwrite. Downloads verify the stored digest, emit a sensitive-access record and return no-store and nosniff headers.MLRO
The tier gate refuses an approval that identity evidence cannot support
Approval checks the identity evidence against the tier being granted: CBN Tier 1 requires authoritative electronic verification of a BVN or a NIN, and Tiers 2 and 3 require both. Where the requirement is unmet the approval is refused with the outstanding schemes named. Because no verification provider adapter is built, the practical consequence is worth planning for rather than discovering: in an installation with no verification provider, a tier that requires authoritative evidence cannot be approved through this gate at all. A format-only or mock confirmation is recorded as exactly that and does not satisfy it. The gate refuses; it does not fabricate the verification.Platform
Risk is rated against a version, with the factors kept
The active risk model supplies the factors, values, weights, bands and review cycle. An assessment stores the score together with its factor-level evidence as an immutable record, and re-scores when the customer, KYC tier, status or profile data changes. If no model version is active the platform refuses to produce a rating rather than defaulting the customer to low risk, and the review cycle it computes is what drives the periodic-review and enhanced due-diligence prompts on the customer screen. Enhanced due diligence is triggered categorically as well as by band: a domestic politically exposed person with an otherwise low weighted score still requires it, and the model records that trigger separately for exactly that reason.MLRO and compliance
Lifecycle decisions stay separated for the life of the relationship
Application submission, review, decision, enhanced due-diligence completion, periodic review, profile change and relationship exit are distinct transitions with distinct permissions. An exited customer is retained for regulatory history rather than deleted, and where a privacy request or a legal hold applies the customer screen says so explicitly instead of quietly failing an action.
In the product
The customer profile screen
One screen answers where the relationship stands: identity evidence and its verification state, the ownership chain, the current risk rating and its factors, the outstanding obligations, and the actions this particular signed-in role is allowed to take.
Placeholder — TODO: capture the customer profile screen (/customers/{id}) from a seeded demonstration tenant — no screenshot of it exists yet. Replace with sourced, approved content before this page is made public.
/customers/{id}customer profile
Screenshot slot. Capture from a seeded demonstration tenant with synthetic data and replace this frame. Do not substitute a mock-up of the interface.
What the capture must show
- Where this relationship standsThe obligation summary: identifiers verified, accounts, periodic review date, enhanced due-diligence status, and whether an application is awaiting review.
- Identifiers and verification stateEach scheme with its masked hint and one of three states: verified, format-checked — labelled in the tooltip as no authority having been contacted — or unverified. Revealing the full values is one audited action for the whole list.
- Beneficial ownershipThe declared chain with percentages and control basis, verification recorded separately from declaration, and closed historic edges still visible.
- Risk decompositionThe score dial, the rating history with its trend, and a factor-by-factor table of value, matched rule, score, weight and contribution that totals to the rating — with missing inputs and unmatched rules flagged rather than scored as zero.
- Lifecycle and holdsEnhanced due-diligence prompts, periodic review overdue warnings, and explicit notices where a legal hold or a privacy request constrains what can be done.
- Refusals, shown as refusalsActions the signed-in role may not take are stated as refusals with a reason, not hidden — an analyst should be able to see that a control exists.
Controls
What makes the record defensible
Each of these maps to a control objective in the institution's own matrix, and each produces evidence rather than an assurance.
Per-subject encryption keys
Identifiers, dates of birth, configured names and addresses, investigation notes and document bytes are encrypted under a key belonging to that data subject, derived from a tenant key, derived from a root key held in an external secret store. Destroying one subject's key makes that person's identity fields permanently unreadable while the transactional skeleton AML law requires survives.Capture and approval are different rights
Front office can create and submit but cannot review or decide. Review and decision are separate again, and revealing an active identifier is an MLRO-level action that writes a sensitive-access record. The negative tests in the release suite prove the refusals, not just the permissions.Ownership history is closed, not deleted
A superseded ownership edge is closed with its effective dates and retained. The question an examiner asks is who controlled this entity on the date of the transaction, and that question has no answer in a system that overwrites the current owner list.Form and storage vocabulary are tested for parity
Every CDD form key must map to a supported storage location, and the parity between the form schema and the database vocabulary is a test rather than a convention. Unknown future keys are preserved rather than silently discarded, so a pack update cannot lose an answer.Nigerian reference data is embedded, not fetched
The 774 states, LGAs and FCT area councils ship with the product, and country codes are canonicalised against a pinned CLDR vocabulary. No lookup leaves the building, which is what makes the address controls work in an air-gapped installation. Raw submitted values are never echoed back in an error message.Sensitive reads are audited as reads
Viewing an unmasked profile, revealing an identifier and downloading a document each create a PII-access record with the actor, the subject and the time — recorded as metadata, never as a URL or a query string, so the audit trail does not become a second copy of the customer database.
Where the edges are
Identity verification is a seam, and it says so
This is the single most misrepresented capability in the AML market. The platform can hold, encrypt, index and govern an identifier. It cannot tell you that NIBSS confirmed it, because nothing in this build has ever asked NIBSS anything.
In the product today
- Capture, encryption, blind-index search, audited reveal and lifecycle for BVN, NIN, CAC, TIN, SCUML, passport, driver's licence and voter's card.
- CBN tier requirement enforcement at approval, with the outstanding identifier schemes named in the refusal.
- Beneficial ownership declaration with cycle and reachability validation, independent verification recording, and closed historic edges.
- Versioned risk models with factor-level evidence, review-cycle calculation, re-scoring on material change, and an explicit refusal when no model is active.
- Encrypted write-once document evidence with digest verification, audited download and no application delete path.
Not claimed here
- Electronic verification against NIBSS, NIMC or the Corporate Affairs Commission. The adapter interface, timeout, retry and provenance rules exist; no provider client does, and no credentials are held.
- Automatic beneficial-ownership confirmation against the CAC register — the same missing adapter. Ownership verification today is a recorded human act.
- Sanctions and PEP status as an attribute of the customer record. That is screening, it is versioned separately, and it is described on its own page.
- A demonstration fixture is available for QA so the verification workflow can be exercised end to end. It carries no data of its own, is stamped non-authoritative, and both it and the registry refuse to run when the environment is production.
- Legal approval of what may be erased under the NDPA against the five-year AML retention floor. The cryptographic mechanism is built; the policy decision is the institution's.
Keep reading
Related capabilities
Customer risk is an input to monitoring and screening, and everything recorded here is subject to the same retention, hold and sensitive-access rules.
Bring your CDD form
We will configure your actual onboarding form in the session
Your fields, your conditional sections, your tier rules and your risk factors — configured live against the schema validator, so you can see exactly which of your requirements the model already supports and which need a decision.