odeling identity verification as evidence, review steps, provider results, and controlled decisions.
A single is_verified field cannot represent a real KYC process.
Identity verification may include personal information, identity documents, a selfie or liveness check, proof of address, national identity databases, sanctions screening, and staff review. Different products may require different subsets, and external providers can return inconclusive results.
The platform needs to know what was checked, which evidence was used, who made the decision, and what remains incomplete.
Separate KYC information from KYC progress
Customer information and workflow status serve different purposes.
The information record can contain submitted identity attributes and secure references to evidence. A process record can track the status of each step:
personal information
identity document
selfie or liveness
address verification
database verification
manual review
overall status
This allows one step to be rejected or resubmitted without discarding completed evidence from another step.
Use explicit step states
Useful states include not started, pending, under review, approved, rejected, and requiring resubmission.
Overall approval should be derived from required steps and policy, not updated casually by whichever provider responds last.
Abstract verification providers
Different identity providers may support different documents, countries, database checks, or biometric requirements. The application service should define operations such as verifying a national identifier or performing a biometric-backed check.
The adapter handles provider authentication and response formats. The domain layer records a normalized outcome and preserves a restricted raw response for investigation.
Provider changes should be configuration decisions where possible. They should not alter the customer’s KYC record structure.
Validate evidence before transmission
Images and documents should be validated for presence, supported type, and size before being sent externally. Stored media should use protected object references and short-lived access URLs rather than permanent public links.
Avoid logging full identifiers, document images, biometric material, or raw provider payloads containing personal data.
Keep an append-only audit log
Every review action should record:
- KYC process;
- step affected;
- previous and new status;
- staff or system actor;
- timestamp;
- decision reason; and
- provider reference where appropriate.
Editing the current status is necessary for product behavior. The audit log preserves how that status was reached.
Control retries and lockouts
Repeated failed verification attempts may require cooldowns or manual review. Retry limits should be enforced consistently and represented in the workflow rather than scattered across endpoints.
Exact thresholds and risk rules should remain confidential.
The design principle
KYC is a decision workflow built from evidence. A mature implementation models the steps, provider checks, review decisions, retry policy, and audit history separately.
That structure supports multiple providers and evolving compliance requirements without reducing identity verification to an unexplained checkbox.
Top comments (0)