H· Hawiyati Documentation

KYC & Identity Verification

Hawiyati's Know Your Customer (KYC) engine provides identity verification workflows that elevate end-user accounts from unverified (L0) to high-assurance verified (L4). Verification is performed locally — no documents or biometrics are sent to cloud services.

Hawiyati's Know Your Customer (KYC) engine provides identity verification workflows that elevate end-user accounts from unverified (L0) to high-assurance verified (L4). Verification is performed locally — no documents or biometrics are sent to cloud services.

Hawiyati IAM Platform — Component Architecture HAWIYATI IAM PLATFORM — COMPONENT ARCHITECTURE Spring Boot 3.5 · Java 25 · gRPC EXTERNAL ACTORS ENTRY LAYER & FEDERATION HTTPS · SAML 2.0 · OIDC · WebAuthn PLATFORM SERVICES HTTPS internal · gRPC DATA & INFRASTRUCTURE JDBC · Redis pub/sub · gRPC User Browser Browser · Mobile App Administrator Admin Console SAML Service Provider SAML 2.0 OIDC Relying Party OIDC · OAuth 2.0 SCIM Client HR System · Directory hawiyati-gateway Spring Cloud Gateway · :8080 Routing · TLS termination hawiyati-http-server IdP Login · MFA · FIDO2 · :8085 SAML ACS · OIDC callback · Account BFF hawiyati-federation SAML 2.0 · OIDC · :8087 Assertion & token issuance · Policy hawiyati-admin Admin Console · :8095 · WebFlux hawiyati-account Account Portal · :8096 · BFF/OIDC hawiyati-scim SCIM 2.0 API · :8098 hawiyati-session · :9004 hawiyati-cache · :9003 hawiyati-infra · :9002 PostgreSQL hawiyati · hawiyati_identity Redis / Valkey Sessions · Cache · Rate limits Audit & Logs CEF Syslog · OTel · SIEM PKI & Keystore SAML · OIDC · mkcert TLS External Actor External System Entry / Federation Platform Service gRPC Service Data Store

The sections below cover KYC workflows, identity verification, and assurance levels. For a full module map with ports, gRPC boundaries, and deployment topology, see the Implementation Guide.

What is KYC in Hawiyati

Hawiyati's Know Your Customer (KYC) engine provides identity verification workflows that elevate end-user accounts from unverified (L0) to high-assurance verified (L4). Verification is performed locally — no documents or biometrics are sent to cloud services.

KYC in Hawiyati is a multi-stage workflow system that captures document evidence, performs automated OCR and MRZ validation, optionally captures selfie and liveness data, and — for the highest assurance levels — routes sessions to a human reviewer queue. The outcome is a verified assurance level stored in kyc_profiles.current_level, which service providers can query to gate access to sensitive features.

KYC workflows are initiated by end users through the account portal, by service providers redirecting users for verification, or by administrators triggering reverification. The customer organization owns the operational decisions: which documents are acceptable, what assurance level is required per use case, who may serve as a human reviewer, and how to handle appeals.

ℹ️
Scope

Hawiyati implements Basic, Standard, Strong, High Assurance, and Reverification workflows. Workflow names and L2/L3/L4 implementation outcomes do not by themselves establish regulatory equivalence for any specific jurisdiction.


Assurance Levels L0–L4

Hawiyati uses five assurance levels aligned with NIST SP 800-63A-4. Each level represents a higher degree of confidence in the claimed identity.

Level Badge Name Evidence Required KYC Workflow What it enables
L0 L0 Unverified None — account created, email or phone present — Basic SP access where no identity assurance is required
L1 L1 Basic Email and phone number both verified via OTP Basic SP access requiring verified contact information; reduced velocity limits
L2 L2 Standard Government-issued photo ID (OCR + MRZ validation) Standard Regulated services, financial applications, government portals
L3 L3 Strong Photo ID + selfie with passive liveness + face match Strong High-value transactions, healthcare, sensitive government services — frozen until biometric review approved
L4 L4 High Assurance L3 evidence + human reviewer approval gate High Assurance Critical national infrastructure access, high-value financial operations — frozen until human review complete
⚠️
L3 and L4 Frozen Pending Approval

Accounts that complete L3 or L4 verification steps remain in UNDER_REVIEW status until a biometric reviewer (L3) or human reviewer (L4) grants approval. The user's assurance level in kyc_profiles.current_level is not elevated until the reviewer action is recorded. Service providers must handle the UNDER_REVIEW intermediate state gracefully.

Assurance Level and SP Policy

Service providers declare a minimum assurance level in their policy configuration. When a user authenticates to an SP with a minimum assurance requirement, Hawiyati evaluates kyc_profiles.current_level against the SP's configured minimum:

  • If current_level >= minimum_level → authentication proceeds
  • If current_level < minimum_level → user is redirected to the KYC portal to complete verification before access is granted
  • If a KYC session is UNDER_REVIEW → SP receives an intermediate response; it should display a "verification pending" message

Source of Truth for Assurance Level

🚫
Critical: Do Not Use users.assurance_level

The users.assurance_level column exists for historical reasons and must never be used as the authoritative assurance level. It may be stale or inconsistent. The only authoritative source is kyc_profiles.current_level in the hawiyati_identity schema.

ColumnTableSchemaUse
current_level kyc_profiles hawiyati_identity Authoritative. Always use this.
assurance_level users hawiyati_identity Legacy column. Do not read or write. Pending deprecation.

All Hawiyati services that need the assurance level must query kyc_profiles joined on user_id. The kyc_profiles row is created when the first KYC session is initiated and updated each time a session reaches a terminal approved state.


KYC Workflow Overview

KYC journey from consent through final decision and reverification
Document processing, biometric checks, risk decisions, and human review are selected by the configured assurance workflow.

All KYC workflows share a common skeleton. They differ in which verification steps are mandatory and whether a human review gate is included before the final decision.

User Browser
hawiyati-http-server
OCR / KYC Engine
PostgreSQL
Admin Reviewer
1
User→http-server→PostgreSQL
Consent screen presented. User accepts data processing notice. Consent timestamp + version recorded. kyc_sessions row created with status IN_PROGRESS for the selected workflow type.
2
User→http-server
User photographs or uploads identity document (national ID, passport, or driver's licence). Image stored on-premise — no external cloud OCR service called.
3
http-server→OCR / KYC Engine→PostgreSQL
OCR extracts text fields. MRZ check digits validated. Fields cross-referenced with MRZ values. Document fingerprint computed (SHA-256 of normalized content) for duplicate detection. Session → DOCUMENT_SUBMITTED.
4
User→http-server→KYC Engine
Standard / Strong / L4 only: user captures selfie. Face match score computed against ID photo (stored in face_match_score). Strong and L4 also run passive liveness detection. Skipped for Basic (L1) workflow.
5
KYC Engine→PostgreSQL
Automated risk decision: document validity · face score thresholds · duplicate fingerprint check · risk signals. If all pass → session may route directly to APPROVED. If any flag triggered or L3/L4 workflow → session → UNDER_REVIEW.
6
Admin Reviewer→http-server→PostgreSQL
Human review (L4 always; others when flagged): Reviewer inspects evidence in Admin Console → APPROVE / REJECT / REQUEST_MORE_INFO.
7
http-server→PostgreSQL→User
APPROVED: kyc_profiles.current_level updated to target assurance level; session → APPROVED. Completion token issued to SP. Audit event emitted.
REJECTED: session → REJECTED; assurance level unchanged; retry per policy.

Common Flow Steps

1
Consent
User is presented with a data processing notice and gives explicit consent before any personal data is collected. Consent timestamp and version are recorded in the KYC session record.
2
Session Creation
A kyc_sessions row is created in state IN_PROGRESS with the configured workflow type (BASIC, STANDARD, STRONG, HIGH_ASSURANCE, REVERIFICATION). The session binds to the authenticated user and the originating SP context.
3
Document Capture
User photographs or uploads their identity document. The image is stored locally. No external cloud OCR service is called — all processing is on-premise.
4
OCR & MRZ Validation
The document image is processed by the OCR engine. For MRZ-bearing documents (passports, national IDs), MRZ check digits are validated and OCR-extracted fields are cross-referenced against MRZ values. Session transitions to DOCUMENT_SUBMITTED.
5
Selfie / Liveness / Face Match Standard+ only
For Standard, Strong, and High Assurance workflows: user captures a selfie. The face is matched against the ID photo. For Strong and High Assurance: passive liveness is checked to confirm a live person (not a photo). The face match score is stored in kyc_sessions.face_match_score (DOUBLE PRECISION).
6
Risk Decision
The automated decision engine evaluates document validity, face match score (if applicable), document fingerprint (duplicate check), and any risk signals. If thresholds are met, the session proceeds to automated approval. If signals trigger a review flag, the session routes to the human review queue.
7
Human Review Gate High Assurance only
For High Assurance (L4) workflows and any session that triggered a review flag: a human reviewer inspects the session evidence in the admin console. The reviewer can APPROVE, REJECT, or REQUEST_MORE_INFO.
8
Decision & Profile Update
On APPROVED: kyc_profiles.current_level is updated to the workflow's target assurance level. The session enters APPROVED state. An audit event is emitted. On REJECTED: session enters REJECTED state; kyc_profiles is unchanged.

Basic Workflow (L1)

The Basic workflow elevates an account to L1 by verifying both email address and phone number via one-time codes. No document capture is required.

Basic Email + Phone OTP Verification
Target assurance level: L1  ·  Selfie: No  ·  Human review: No
1
Consent & Session Start
User accepts data processing notice. KYC session created in IN_PROGRESS.
2
Email OTP Sent
A 6-digit OTP is sent to the user's registered email address. The code has a 10-minute TTL and is stored in Redis.
3
Email OTP Verified
User submits the OTP. On success, users.email_verified = true is set and the email verification event is audited.
4
SMS OTP Sent
A 6-digit OTP is sent to the user's registered phone number via the configured SMS gateway. Code TTL: 5 minutes.
5
SMS OTP Verified
User submits the OTP. On success, users.phone_verified = true is set.
6
Approved — Level Elevated to L1
kyc_profiles.current_level set to L1. Session state: APPROVED. Audit event emitted.

Standard Workflow (L2)

The Standard workflow elevates an account to L2 by verifying a government-issued photo ID and capturing a selfie for face matching.

Standard Document + Selfie + Face Match
Target assurance level: L2  ·  Selfie: Yes  ·  Liveness: No  ·  Human review: No (unless triggered by risk flag)
1
Consent & Session Start
User accepts biometric data processing notice (required for selfie capture). KYC session created.
2
Document Capture
User photographs front (and back, if national ID) of their identity document. Accepted: Passport, National ID, Driver's Licence.
3
OCR & MRZ Validation
OCR engine extracts name, DOB, nationality, document number, expiry. MRZ check digits validated. Document expiry enforced. Duplicate fingerprint check performed.
4
Selfie Capture & Face Match
User captures a selfie. The face match algorithm compares the selfie to the ID photo. Score stored in face_match_score. Threshold is configurable per policy.
5
Automated Risk Decision
Decision engine evaluates all signals. If a duplicate document fingerprint is detected, session routes to manual review instead of auto-approving.
6
Approved — Level Elevated to L2
kyc_profiles.current_level set to L2. Session: APPROVED.

Strong Workflow (L3)

The Strong workflow elevates an account to L3 by adding passive liveness detection to the selfie step. L3 sessions enter UNDER_REVIEW pending biometric team approval.

Strong Document + Selfie + Passive Liveness + Face Match
Target assurance level: L3  ·  Selfie: Yes  ·  Liveness: Passive  ·  Human review: Biometric reviewer required
⚠️
Frozen Until Biometric Approval

Even when all automated checks pass, the session remains in UNDER_REVIEW and kyc_profiles.current_level remains at its prior value until a biometric reviewer explicitly approves the session in the admin console.

The Strong workflow follows the same steps as Standard, with the addition of passive liveness detection at step 4. The liveness module analyzes the selfie image for indicators of a live subject (anti-spoofing). If liveness fails, the session is immediately rejected; the user may retry after a configured cooling-off period.

L3 Biometric Review Queue

After all automated checks pass, the session enters the Biometric Review Queue in the admin console. A reviewer with the BIOMETRIC_REVIEWER role sees the session evidence: ID front/back images, the selfie, the face match score, and the liveness signal result. The reviewer can:

  • APPROVE — kyc_profiles.current_level updated to L3
  • REJECT — session moves to REJECTED; kyc_profiles unchanged
  • REQUEST_MORE_INFO — session remains in UNDER_REVIEW; user receives notification

High Assurance Workflow (L4)

The High Assurance workflow elevates an account to L4. It includes all Strong workflow steps plus a mandatory human reviewer gate before any approval is granted.

High Assurance Full Evidence + Mandatory Human Review
Target assurance level: L4  ·  Selfie: Yes  ·  Liveness: Passive  ·  Human review: Mandatory
🚫
No Automated Approval for L4

High Assurance sessions can never be auto-approved. Every L4 session must pass through the human review gate. The review queue must be staffed during business hours. Unreviewed sessions remain in UNDER_REVIEW indefinitely until a reviewer acts.

The High Assurance workflow collects the same evidence as Strong (document + liveness selfie + face match), then unconditionally routes to the human reviewer queue. The reviewer sees the full evidence package and applies their judgment before an approval decision is recorded. All reviewer actions are audit-logged with the reviewer's identity, timestamp, and any notes provided.


Reverification Workflow

Reverification allows an already-verified user to re-submit evidence to renew their assurance level or to re-verify after a document expiry or a security event.

Reverification Re-verify an Existing User
Target assurance level: Same as original workflow  ·  Triggers: Document expiry, SP policy, admin action, security event

Reverification is triggered when:

  • The user's identity document captured during a previous verification session has expired
  • An SP requires re-verification at a configured interval (e.g., annually for financial services)
  • An administrator marks the user's KYC profile as REVERIFICATION_REQUIRED
  • A security event (e.g., suspected account takeover) triggers re-verification as a protective measure

During reverification, the user follows the same steps as their original workflow type. If the reverification succeeds, kyc_profiles.current_level is refreshed (the timestamp updated). If the reverification fails or is rejected, kyc_profiles.current_level may be downgraded depending on the configured downgrade policy.

ℹ️
Document Continuity

The user may re-submit the same document type or switch to a different accepted document. The document fingerprint is re-computed. If the new fingerprint matches a previously seen fingerprint from a different user, the duplicate signal routes the session to manual review.


KYC Session States

Each KYC session has a lifecycle tracked in kyc_sessions.status. States are named constants defined in KycWorkflowCode.java.

NOT_STARTED
KYC profile exists but no session has been initiated for this workflow type.
IN_PROGRESS
Session created, consent given. User is completing verification steps. This is the active working state.
DOCUMENT_SUBMITTED
Document capture complete. OCR/MRZ processing has begun or completed. Awaiting selfie capture (if required) or risk decision.
UNDER_REVIEW
Session is in the human (or biometric) reviewer queue. Automated steps completed. Awaiting reviewer action. L3/L4 always pass through here.
APPROVED
Session approved. kyc_profiles.current_level has been updated to the target assurance level. Terminal state.
REJECTED
Session rejected by automated check or human reviewer. The user's assurance level is unchanged. Retry is subject to the retry policy.
EXPIRED
The session was not completed within the session TTL (default: 30 minutes of inactivity). A new session must be started.
REVERIFICATION_REQUIRED
Set on the kyc_profile (not a session state) to flag that the user must re-verify before the next SP interaction requiring KYC.

State Transition Flow

The diagram below shows how a KYC session moves through states for each workflow type. ⇢ indicates a conditional branch.

0
NOT_STARTED
KYC profile created but no session initiated. User has not yet started the verification process for this workflow type.
1
IN_PROGRESS
Session created, consent given. User is completing verification steps.
⇢ OCR/MRZ fail, liveness fail → REJECTED
⇢ 30 min inactivity → EXPIRED
2
DOCUMENT_SUBMITTED
Document capture complete; OCR/MRZ processing finished. Risk engine evaluates all signals.
⇢ All checks pass (Basic/Standard, no risk flag) → APPROVED
⇢ Duplicate fingerprint, low face score, or L3/L4 workflow → UNDER_REVIEW
3
UNDER_REVIEW L3 / L4 gate
Session held in the biometric/human reviewer queue. The user's current assurance level is unchanged during review.
⇢ Reviewer approves → APPROVED
⇢ Reviewer rejects → REJECTED
⇢ Reviewer requests more info → stays in UNDER_REVIEW
4
APPROVED ✓
kyc_profiles.current_level updated to the target assurance level atomically with last_verified_at. Audit event KYC_SESSION_APPROVED emitted. Notification dispatched. Terminal state.
REJECTED — automated check or reviewer denial. User's level unchanged. Retry subject to retry policy (max 3/24h).
EXPIRED — session inactivity TTL exceeded (default 30 min). New session required.

State Transition Flow

NOT_STARTED
→
Initial state. KYC profile exists but no session for this workflow has been initiated. Transitions to IN_PROGRESS when user begins the flow.
IN_PROGRESS
→
Active working state. User is completing steps (consent → document capture → selfie). Transitions to DOCUMENT_SUBMITTED on document upload, or EXPIRED on timeout (30 min inactivity).
DOCUMENT_SUBMITTED
→
Document captured and OCR/MRZ processing complete. Awaiting selfie (Standard+) or automated risk decision. Transitions to UNDER_REVIEW or directly to APPROVED/REJECTED.
UNDER_REVIEW
→
Frozen — no user action possible. Human reviewer in Admin Console must APPROVE, REJECT, or REQUEST_MORE_INFO. L3/L4 always pass here; other workflows route here when risk flags triggered.
APPROVED ✓
—
Terminal (success). kyc_profiles.current_level updated to the workflow's target assurance level. Completion token issued to SP. Audit event emitted.
REJECTED ✗
—
Terminal (failure). Assurance level unchanged. Retry subject to the retry policy (cooldown + max-attempts). User notified.
EXPIRED
—
Terminal (timeout). Session not completed within TTL. User must start a new session. Partial data is discarded.

State Transitions

FromToTriggerActor
— IN_PROGRESS User initiates KYC, consent given, session created End user / system
IN_PROGRESS DOCUMENT_SUBMITTED Document upload and OCR processing complete System
DOCUMENT_SUBMITTED APPROVED All automated checks pass (Basic/Standard without risk flag) System (automated)
DOCUMENT_SUBMITTED UNDER_REVIEW Risk flag triggered (duplicate fingerprint, low face score), or workflow is Strong/High Assurance System → reviewer queue
UNDER_REVIEW APPROVED Reviewer grants approval Human reviewer
UNDER_REVIEW REJECTED Reviewer rejects; or automated checks fail on re-analysis Human reviewer / system
IN_PROGRESS REJECTED OCR validation fails, MRZ check digits invalid, document expired, liveness failed (Strong+) System
IN_PROGRESS EXPIRED Session inactivity TTL exceeded (30 min default) System (scheduled cleanup)
DOCUMENT_SUBMITTED EXPIRED Session inactivity TTL exceeded System

On REJECTED — Retry Policy

When a session is rejected, the user may start a new KYC session subject to the configured retry limits:

  • Default: maximum 3 attempts per 24-hour period
  • After 3 rejections: account flagged; admin review required before another attempt is permitted
  • Rejection reason codes are included in the audit event; the user-facing message is generic (no specific failure detail exposed to prevent enumeration)

On APPROVED — Profile Update

When a session is approved, the following updates occur atomically:

  • kyc_profiles.current_level updated to target level
  • kyc_profiles.last_verified_at updated to current timestamp
  • kyc_profiles.last_session_id updated to the approved session ID
  • Audit event emitted: KYC_SESSION_APPROVED with session ID, workflow type, target level, actor (system or reviewer ID)
  • Notification dispatch queued (subject to notification delivery configuration)

Frozen L3/L4 States

⚠️
Intermediate State Handling Required

Service providers that support L3 or L4 access must implement handling for the UNDER_REVIEW intermediate state. An account in UNDER_REVIEW has completed all automated steps but has not yet received reviewer approval. The account's current assurance level remains at its pre-verification value during this period.

The UNDER_REVIEW state is a required intermediate step for all L3 and L4 verifications. It exists because biometric and human review cannot be fully automated — a reviewer must inspect the evidence and make a judgment call. During this period:

  • The user's kyc_profiles.current_level remains at its previous value (e.g., L2 if the user was previously L2-verified)
  • The user can continue using services at their existing assurance level
  • Services that require L3 or L4 must display a "verification under review" message and defer access
  • The review SLA is defined by the customer organization's operations team — Hawiyati does not enforce a specific SLA

The admin console provides a dedicated review queue view filtered to UNDER_REVIEW sessions. Reviewers are notified via the configured notification channel when new sessions enter the queue.


Supported Documents

Hawiyati's OCR engine supports MRZ-bearing identity documents following ICAO 9303 specifications. Non-MRZ documents may be captured but receive OCR-only validation without MRZ cross-reference.

Document Type Format MRZ Standard Fields Extracted Notes
Passport TD3 (booklet) ICAO 9303 TD3 (2-line MRZ) Surname, given names, nationality, DOB, sex, expiry, document number, issuing country Most reliable MRZ format; preferred document type
National ID Card TD1 (card ID-1) ICAO 9303 TD1 (3-line MRZ) Surname, given names, nationality, DOB, sex, expiry, document number, optional fields Front + back capture required; optional field content varies by issuing country
National ID Card (larger) TD2 (card ID-2) ICAO 9303 TD2 (2-line MRZ) Surname, given names, nationality, DOB, expiry, document number Less common; supported where issued
Driver's Licence Jurisdiction-specific OCR only (no standard MRZ) Name, DOB, licence number, expiry (jurisdiction-dependent field layout) No MRZ cross-validation; lower confidence; not recommended for L3/L4
ℹ️
Country Support

The supported country list is jurisdiction-dependent and configured per deployment. Not all countries' national ID formats are pre-trained in the OCR model. The customer must confirm which document types are acceptable for their use case and configure the accepted-documents policy accordingly.

Document Expiry Enforcement

Hawiyati enforces document expiry at the point of capture. If the extracted expiry date (from OCR or MRZ) is in the past, the session is immediately rejected with reason code DOCUMENT_EXPIRED. The customer may configure a grace period (default: 0 days) for documents in the process of renewal.


OCR & MRZ Validation

For MRZ-bearing documents, Hawiyati performs a two-step validation:

1
OCR Field Extraction
The document image is passed to the OCR engine. Visual fields are extracted: name, date of birth, nationality, document number, expiry date, issuing authority.
2
MRZ Parsing
The MRZ zone at the bottom of the document is separately decoded. Each field and check digit is parsed according to the ICAO 9303 standard for the document format (TD1/TD2/TD3).
3
Check Digit Validation
All MRZ check digits are computed and compared against the MRZ values. A check digit mismatch indicates a tampered or unreadable document and immediately rejects the session.
4
Cross-Reference Validation
Key fields from OCR are cross-referenced against MRZ values (e.g., document number, DOB, expiry). Significant mismatches between OCR and MRZ trigger a manual review flag rather than an automatic rejection, allowing for OCR imperfection tolerance.

Results of OCR and MRZ validation are stored in kyc_sessions and included in the evidence package visible to human reviewers. Field-level confidence scores (where the OCR engine provides them) are also stored.


Document Fingerprinting

Hawiyati computes a cryptographic fingerprint for each submitted document to detect reuse of the same physical document across multiple accounts.

How It Works

After successful OCR/MRZ extraction, Hawiyati computes:

Fingerprint computation
HMAC-SHA256( key = deployment_secret_key, data = normalize(country_code + "|" + document_type + "|" + document_number) )

The normalized input is case-folded, whitespace-stripped, and canonicalized. The resulting HMAC-SHA256 digest is stored in kyc_documents.fingerprint. This means Hawiyati never stores the raw document number — only the fingerprint.

🔑
Fingerprint is a Signal, Not a Hard Block

A duplicate fingerprint (same document used across multiple accounts) is a manual review signal, not an automatic rejection. The session is routed to the human review queue where a reviewer can determine whether the duplication represents fraud, a data entry error, or a legitimate shared-document scenario (rare).

Privacy Properties

  • The raw document number is never stored in kyc_documents
  • The HMAC key is deployment-specific and stored in the secrets manager
  • Without the HMAC key, a fingerprint cannot be reversed to recover the document number
  • Fingerprints are salted by deployment — fingerprints from different Hawiyati deployments are not comparable

Selfie & Liveness Detection

Selfie capture and face matching are required for Standard, Strong, and High Assurance workflows. Liveness detection is added in Strong and High Assurance to prevent spoofing with a photograph.

WorkflowSelfieFace MatchLiveness
Basic (L1)———
Standard (L2)YesYesNo
Strong (L3)YesYesPassive
High Assurance (L4)YesYesPassive

Face Matching

The face match algorithm compares the selfie image to the face region extracted from the identity document photo. The similarity score (0.0–1.0) is stored in kyc_sessions.face_match_score as a DOUBLE PRECISION column. The acceptance threshold is configurable per deployment (default: 0.80). Sessions with a score below the threshold are routed to manual review.

Passive Liveness

Passive liveness analyzes a single selfie frame for anti-spoofing signals (texture analysis, 3D depth cues, print/screen artifact detection). No action is required from the user. The liveness result is binary: LIVE or SPOOF. A SPOOF result immediately rejects the session with a cooling-off period before the user may retry.

Data Handling

⚠️
Biometric Data Retention

Selfie images and document images are stored locally in the KYC evidence store. The customer is responsible for defining the retention period and deletion policy in accordance with applicable biometric data protection laws. Hawiyati provides deletion APIs; the customer must configure and trigger the retention schedule. Default policy: retain for 7 years or until user deletion request, whichever is sooner — this default must be reviewed against local law before production deployment.


Human Review Gate

The human review gate is the mandatory approval step for High Assurance (L4) sessions and the optional escalation path for sessions that triggered automated risk signals.

When the Review Gate Triggers

  • Always: High Assurance (L4) workflow — every session passes through human review
  • Always: Strong (L3) workflow — biometric reviewer must approve before level is elevated
  • Conditional: Duplicate document fingerprint detected on any workflow
  • Conditional: Face match score below threshold on Standard workflow
  • Conditional: OCR/MRZ field cross-reference mismatch beyond tolerance
  • Conditional: Risk score exceeds configured threshold during the KYC session

Reviewer Queue

The reviewer queue is accessible in the admin console under KYC → Review Queue. Each queue entry shows:

  • Session ID, user identifier, workflow type, time in queue
  • Reason for manual routing (e.g., DUPLICATE_FINGERPRINT, FACE_MATCH_BELOW_THRESHOLD, WORKFLOW_REQUIRES_REVIEW)
  • Document images (front, back if applicable)
  • Selfie image (if captured)
  • Face match score and liveness result
  • OCR/MRZ extracted fields and any cross-reference discrepancies
  • Document fingerprint status (unique or duplicate)

Reviewer Actions

ActionSession StateLevel UpdatedEffect
APPROVE APPROVED Yes — set to target level User's assurance level elevated; notification queued; audit event emitted
REJECT REJECTED No Rejection reason recorded; user may retry subject to retry policy
REQUEST_MORE_INFO UNDER_REVIEW (stays) No User notified with a message from the reviewer; user can submit additional evidence

Audit Trail

Every reviewer action generates an audit event that records: reviewer operator ID, session ID, action taken, timestamp, and any notes the reviewer added. This audit trail is retained alongside the session record and forms part of the compliance evidence package for L4 verifications.

✓
SLA Recommendation

Define and staff a review SLA for your deployment. Users with sessions in UNDER_REVIEW cannot access L3/L4 services until reviewed. Common SLAs: 4 hours for business-hours submissions, 24 hours for off-hours submissions. Hawiyati does not enforce an SLA — this is an operational responsibility.


KYC Admin Operations

Viewing KYC Sessions

Navigate to Admin Console → KYC → Sessions. The sessions view supports filtering by:

  • Status (IN_PROGRESS, UNDER_REVIEW, APPROVED, REJECTED, EXPIRED)
  • Workflow type (Basic, Standard, Strong, High Assurance, Reverification)
  • Target assurance level
  • Date range (created at, completed at)
  • User identifier or username

Manual Admin Actions

ActionWhenEffect
Approve session Session is UNDER_REVIEW Moves session to APPROVED; updates kyc_profiles.current_level
Reject session Session is UNDER_REVIEW or IN_PROGRESS Moves session to REJECTED; level unchanged
Trigger reverification Any user Sets kyc_profiles.status = REVERIFICATION_REQUIRED; user prompted on next login
Downgrade assurance level Admin action or security event Directly updates kyc_profiles.current_level; audit event emitted
Export KYC report Any time Exports session data as CSV or JSON (up to 50,000 rows)

KYC Dashboard

The KYC dashboard at Admin Console → KYC → Dashboard shows real-time metrics:

  • Sessions by status (pie/count view)
  • Sessions in UNDER_REVIEW (queue depth)
  • Average time in queue (current day, 7-day rolling)
  • Approval vs rejection rate by workflow type
  • Assurance level distribution across all users

Notifications

⚠️
Notification Delivery: Operational Ownership Required

KYC decision email templates (approved, rejected) exist in the system, but automatic approved/rejected delivery is not currently a verified trigger in all deployment configurations. Define operational notification ownership and verify end-to-end delivery before production launch. Do not assume notifications will fire without explicit configuration and testing.

Hawiyati supports notification delivery via the configured email gateway and SMS gateway for KYC events. The following notification types are defined:

EventChannelTemplateDelivery Status
KYC session approved Email kyc-approved.html Template exists; verify trigger configuration
KYC session rejected Email kyc-rejected.html Template exists; verify trigger configuration
Reverification required Email kyc-reverification.html Triggered on admin action
Reviewer request for more info Email kyc-more-info.html Triggered by reviewer REQUEST_MORE_INFO action

All notifications are dispatched via the notification outbox system with exponential backoff (30s / 2m / 8m / 32m / 128m) and idempotency keys. Failed notifications are retried up to 5 times before being marked as failed and requiring manual intervention.


Data Retention & Deletion

Hawiyati stores the following KYC data subject to the customer's retention policy:

DataStorageDefault RetentionCustomer Configurable
KYC session metadata kyc_sessions table (PostgreSQL) 7 years Yes
Document images (front/back) Local evidence store (filesystem or S3-compatible) 7 years Yes — review against local biometric law
Selfie images Local evidence store 7 years Yes — biometric data; stricter laws may apply
OCR extracted fields kyc_documents table 7 years Yes
Document fingerprint kyc_documents table 7 years (used for duplicate detection) Yes
Face match score kyc_sessions.face_match_score 7 years Yes

Deletion requests (e.g., GDPR right to erasure) must be handled by the customer using Hawiyati's deletion APIs. Deletion of a KYC session record also triggers deletion of associated document images. The customer is responsible for ensuring that deletion fulfils all applicable legal requirements.


NIST SP 800-63A Alignment

Hawiyati's KYC assurance levels are designed with reference to NIST SP 800-63A-4 (Digital Identity Guidelines — Enrollment and Identity Proofing). The table below shows the intended alignment:

Hawiyati LevelNIST SP 800-63A ReferenceEvidence BasisNotes
L0 No enrollment (self-asserted) None Below IAL1 threshold
L1 IAL1 (self-asserted with verified contact) Email + phone OTP verified Contact verification only; no identity document
L2 IAL2 (remote identity proofing) Government ID + face match Automated document verification; remote proofing
L3 IAL2 (strengthened) / IAL3 approach Government ID + liveness + face match + biometric review Liveness and reviewer gate strengthen assurance
L4 IAL3 (supervised remote proofing) All L3 evidence + mandatory human review Human review gate analogous to IAL3 operator supervision
⚠️
Regulatory Equivalence Disclaimer

Workflow names and level designations do not by themselves establish regulatory equivalence for any specific jurisdiction or regulatory framework. The customer's compliance and legal teams must assess whether Hawiyati's implementation meets the specific requirements of applicable laws, regulations, or standards in their jurisdiction before representing identity proofing results as compliant with a specific standard.


Customer Responsibilities

Hawiyati provides the KYC workflow engine, evidence capture, automated validation, and reviewer tooling. The customer organization owns the policy decisions, operational processes, and legal compliance.

Responsibility AreaHawiyati ProvidesCustomer Owns
Lawful purpose Consent capture mechanism; audit log of consent Legal basis for collecting and processing identity data; notice content; consent wording
Acceptable documents Document capture and validation engine; accepted-type configuration Which document types are acceptable for each use case; jurisdiction-specific requirements
Thresholds and policy Configurable face match threshold, retry limits, session TTL Threshold values appropriate to risk tolerance; policy review cadence
Reviewer operations Reviewer queue, evidence display, reviewer actions, audit log Staffing the reviewer queue; reviewer training; review SLA; escalation path
Reviewer authority Role-based access control for reviewer and biometric reviewer roles Who may serve as a reviewer; authorization documentation; segregation of duties
Data retention Configurable retention periods; deletion APIs Retention policy compliant with applicable law; scheduling and executing deletions
Appeal and escalation REQUEST_MORE_INFO action; reviewer notes; audit trail Appeal process for rejected applicants; escalation path for disputed decisions
Notification delivery Notification outbox, email/SMS templates, retry logic Gateway configuration; verifying delivery; operational ownership of notification failures
✓
Pre-Launch Checklist

Before going live with KYC: (1) confirm lawful purpose and applicant notice are in place; (2) define and document acceptable document policy; (3) configure and test face match and liveness thresholds; (4) staff the reviewer queue with trained reviewers; (5) define the review SLA; (6) verify notification delivery end-to-end; (7) confirm data retention policy is set and compliant; (8) document the appeal and escalation path; (9) run a full end-to-end KYC test for each workflow type with real documents.

HawiyatiDocumentation · v2026 · Spring Boot 3.5