ADR-018: KYC and digital onboarding architecture¶
| Status | Accepted |
| Date | 2026-04-10 |
| Deciders | CTO, CCO, Head of Product |
| Affects repos | bank-kyc, bank-app, bank-aml |
Status¶
Accepted — 2026-04-10
Context¶
Onboarding is the front door. Getting it wrong creates conversion friction that kills customer acquisition, or creates compliance gaps that regulators find. A dual-jurisdiction bank operating in NZ and AU has different document verification infrastructure, different AML/CFT programme requirements, and different government data access agreements in each country. The design must handle both without creating a fragmented customer experience.
The key tension: onboarding must be fast enough (≤5 min p90, NFR-002) to minimise drop-off, thorough enough to satisfy AML-003 and AML-002, and flexible enough to handle the full spectrum of CDD tiers — standard, simplified, and enhanced.
Decision¶
A KYC orchestration service calls pluggable identity verification adapters. An internal CDD tier assignment engine determines which checks fire and at what depth. All decisions are event-sourced to an immutable audit trail. A single KYC record links to both NZ and AU account instances for dual-jurisdiction customers — no duplicate identity verification.
The five-stage onboarding flow¶
Stage 1 — Capture: Customer enters personal details (name, DOB, address, IRD/TFN if applicable) and uploads identity documents (NZ/AU passport, driver's licence, or accepted alternative).
Stage 2 — eIDV: The orchestration service calls: - DVS (Document Verification Service, AU Home Affairs) for AU documents - DIA (Department of Internal Affairs) for NZ documents - Biometric liveness check to confirm the person holding the document is present - Credit bureau identity confirmation (Equifax, Centrix, or Illion depending on jurisdiction)
A composite identity confidence score is produced. The score determines the CDD tier and what additional checks are required.
Stage 3 — CDD tier assignment: The tier engine assigns Standard, Simplified, or EDD based on: product type, jurisdiction, eIDV confidence, adverse media signals, and whether the customer is a PEP. The tier determines the ongoing monitoring cadence.
Stage 4 — Sanctions screen: Real-time screen against OFAC, UN, MFAT (NZ designated persons), and DFAT (AU autonomous sanctions). A confirmed match is a hard block — no account can be opened. A potential match requires manual adjudication before activation.
Stage 5 — Decision: All checks pass → account activated, virtual card issued instantly. Any check fails → clear customer communication with next steps (either self-serve resolution or agent referral).
Vendor strategy: orchestration layer, not a hardwired provider¶
The identity verification market changes fast. Do not hardwire a single provider. The KYC orchestration service calls pluggable adapters — each provider (Onfido, Veriff, iProov, OCR Labs, Green ID) is behind an interface. Swapping or adding a provider is a configuration change, not a redeployment.
Current NZ/AU provider landscape: - Onfido — document + liveness, strong NZ/AU coverage, API-first - iProov — liveness check specialist, used by major AU banks - Veriff — strong on document variety and fraud detection - OCR Labs — AU-focused, native DVS integration - Green ID (Mitek) — AU-focused, strong credit bureau integration
Government data access — start procurement early: - DVS (AU): Gateway agreement with AU Home Affairs required. This is the gold standard for AU document verification. Takes 4–8 weeks to procure. - DIA (NZ): Approved service provider agreement required for real-time passport/licence verification. Start this process concurrently with RBNZ bank registration.
Risk-based approach — mandatory, not optional¶
Both RBNZ and AUSTRAC require a risk-based AML programme. The onboarding engine assigns one of three CDD tiers:
| Tier | Criteria | Checks | Review cadence |
|---|---|---|---|
| Simplified CDD | Very low risk — limited product, low transaction value, established identity | eIDV only | Triennial |
| Standard CDD | Most retail customers | eIDV + sanctions + adverse media | Triennial |
| Enhanced CDD (EDD) | PEP, high-risk jurisdiction, complex business, large transactions | Full document check + source of funds + senior management approval | Annual |
The tier is assigned automatically by MOD-010 based on the risk factors at onboarding. It is re-evaluated on each trigger event — new product application, change in transaction patterns, PEP identification, or scheduled periodic review.
Single KYC record for dual-jurisdiction customers¶
When a customer holds both a NZ and AU account, one customer record in Postgres links to multiple account records. There is no duplicate identity verification. The AML obligations are per-jurisdiction — both RBNZ and AUSTRAC have separate programme requirements — but the underlying identity assertion is shared.
What this means in the data model:
- customers.kyc_verified_at — timestamp of the last identity verification
- customers.kyc_tier — current CDD tier (applies to all accounts)
- customers.jurisdiction_flags — {nz: true, au: true} — which jurisdictions have been enrolled
- customers.pep_screened_at — last PEP screening timestamp
- customers.sanctions_status — current sanctions clearance status
A customer verified once for their NZ account does not go through the full eIDV flow again when opening an AU account — they confirm their details and receive a shorter re-verification. The risk-based approach allows this because the identity foundation is already established.
When re-verification is required: - Identity documents expire - Periodic review cadence triggers - Significant change in transaction profile - Customer becomes a PEP - Customer self-reports a change in circumstances
Immutable audit trail¶
Every step in the onboarding flow writes to the KYC audit trail (MOD-012): - Which checks were performed and when - Which provider performed each check - The result of each check (pass/fail/manual review) - The composite confidence score - The CDD tier assigned and the reason - The operator ID if a human reviewed any step - The model version for any automated decisions
This is the evidence a regulator asks for. It must be producible without manual compilation — a Snowflake query returns the complete onboarding audit for any customer for any period.
Ongoing monitoring¶
Onboarding is the start, not the end. The event streaming layer triggers re-review when: - Transaction patterns change significantly (Snowflake risk score delta exceeds threshold) - Customer is identified as a PEP during transaction monitoring - Scheduled periodic review date arrives - Customer makes an unusually large transaction or high-value account change - External list update creates a potential sanctions match
This ongoing monitoring is what RBNZ and AUSTRAC actually inspect. A bank with excellent onboarding but no ongoing monitoring fails the AML examination.
Principles alignment¶
| Principle | Assessment | Notes |
|---|---|---|
| AP-001 KISS | ✓ | Orchestration layer with adapters — no hardwired complexity |
| AP-002 Data governance | ✓ | Single KYC record; immutable audit trail; clear ownership |
| AP-003 Compliance | ✓ | GATE on account activation; every obligation documented |
| AP-004 Security | ✓ | Identity data encrypted; access controlled; DVS/DIA access audited |
| AP-005 Customer driven | ✓ | ≤5 min p90; clear communication at every stage |
| AP-007 Evolution | ✓ | Pluggable adapters mean providers can be swapped without redeployment |
Perspectives¶
| Perspective | Assessment | Notes |
|---|---|---|
| Performance & Scalability | ✓ | eIDV APIs are fast; bottleneck is government data services — async where possible |
| Strategy | ✓ | Orchestration layer future-proofs against market consolidation |
| Regulatory | ✓ | GATE on account activation; immutable audit trail for regulator inspection |
| Integration | ~ | DVS and DIA access require government agreements — long lead time |
| Usability | ✓ | ≤5 min p90; biometric reduces document handling friction |
| Resource | ~ | DVS/DIA procurement requires dedicated effort |
See perspectives.md for how to use these evaluation lenses.
Relevant viewpoints¶
- Functional viewpoint — Five-stage onboarding flow; CDD tier decision tree; re-verification triggers
- System viewpoint — KYC orchestration service; eIDV adapter interfaces; sanctions screener; Postgres customer record
- Information viewpoint — Customer record schema; KYC audit trail structure; CDD tier history
- Security viewpoint — Identity data handling; biometric data retention; DVS/DIA access controls
- Operational viewpoint — Failed onboarding queue; manual review workflow; DVS/DIA SLA monitoring
See viewpoints.md for guidance on producing these viewpoints.
Signoff record¶
| Date | Name | Role | Status |
|---|---|---|---|
| 2026-04-10 | Ross Millen | CTO | Approved |
| 2026-04-10 | Ross Millen | Head of Architecture | Approved |
| 2026-04-10 | Ross Millen | Head of Data | Approved |
Capabilities¶
| Capability | Description | Relationship |
|---|---|---|
| CAP-029 | Immutable audit log | enabled — every onboarding step written to KYC audit trail |
| CAP-045 | Digital KYC — document + selfie verification | enabled — eIDV orchestration with pluggable adapters defined here |
| CAP-046 | Real-time account opening (sub-10 minutes) | enabled — five-stage onboarding flow targets ≤5 min p90 |
| CAP-047 | NZ/AU resident onboarding | enabled — dual-jurisdiction CDD, DVS (AU) and DIA (NZ) integration |
| CAP-062 | CDD automatic tier assignment | enabled — automated CDD tier assignment engine based on risk factors |
| CAP-066 | Self-service KYC refresh | enabled — re-verification flow and trigger conditions defined here |
Related decisions¶
| ADR | Title | Relationship |
|---|---|---|
| ADR-001 | Postgres as the OLTP operational store | customer KYC record and sanctions status held in Postgres |
| ADR-014 | Deposit and lending product set — launch sequencing | onboarding is the gateway to all products |
| ADR-026 | Customer authentication — Cognito, mobile-first, passwordless | passkey registered at end of onboarding |
All ADRs
Compiled 2026-05-22 from source/entities/adrs/ADR-018.yaml