KYC and Identity Verification Domain - KYC and AML effects on underwriting eligibility
Overview
This domain is the underwriting gate that decides whether an applicant can move from identity and compliance checks into score execution. In this code path, KYC and AML signals are not treated as a separate utility; they are eligibility controls that can stop scoring entirely with a decline outcome, or route the case to refer for manual review before any model call is made.
The gate is implemented in backend/src/ml/credit_pipeline_validation.py and exercised by backend/tests/ml/test_pipeline_validation.py. The runtime scoring path in backend/src/usecase/credit_score_runtime.py still carries identity-related signals such as kyc_passed, fraud_risk_flag, and aml_risk_flag into the feature set, but the decisive underwriting behavior happens earlier in the gating layer.
Architecture Overview
flowchart TB
subgraph IdentityVerification [Identity Verification and KYC]
KycUsecase[kyc py usecase functions]
KycGateway[KycGateway]
KycUsecase -->|delegates| KycGateway
end
subgraph UnderwritingGate [Pre score underwriting gate]
CanonicalInput[CanonicalCreditInput]
Compute[compute_completeness]
Gate[gate]
Completeness[DataCompletenessReport]
Result[GatingResult]
CanonicalInput --> Compute
Compute --> Completeness
CanonicalInput --> Gate
Gate -->|calls| Compute
Gate --> Result
end
subgraph EligibilityOutcomes [Eligibility outcomes]
Decline[decline]
Refer[refer]
Pass[pass]
end
subgraph RuntimeScoring [Runtime credit scoring]
Score[score_housing_application]
Vertex[_score_with_vertex]
Validate[_validate_risk_engine_contract]
Risk[_derive_risk_flags]
Score --> Vertex
Vertex --> Validate
Score --> Risk
end
subgraph Tests [Gate and scoring tests]
DeclineTests[TestDeclineGates]
ReferTests[TestReferGates]
PassTests[TestPassGate]
ScoreTests[TestCompletenessScore]
GateTests[TestGateFunction]
end
KycGateway -->|verification status and risk signals| CanonicalInput
Result -->|decline| Decline
Result -->|refer| Refer
Result -->|pass| Pass
Pass -->|model allowed| Score
DeclineTests --> Compute
ReferTests --> Compute
PassTests --> Compute
ScoreTests --> Compute
GateTests --> Gate
Gating Rules and Eligibility Impact
backend/src/ml/credit_pipeline_validation.py classifies flags into two blocking tiers and one score-based fallback. The gate checks decline flags first, then refer flags, and only then compares completeness against the minimum score threshold.
| Name | Type | Description |
|---|---|---|
MIN_DAYS_COVERED |
int |
Minimum transaction history required before INSUFFICIENT_HISTORY is raised. |
BUREAU_MAX_AGE_DAYS |
float |
Maximum bureau report age before BUREAU_REPORT_STALE is raised. |
MIN_COMPLETENESS_SCORE_TO_PASS |
float |
Fallback minimum completeness score used only when no blocking flags are present. |
_BUREAU_REQUIRED_PRODUCTS |
frozenset[str] |
Product types that require bureau data and emit BUREAU_REQUIRED_BUT_ABSENT when missing. |
_DECLINE_FLAGS |
frozenset[str] |
KYC_NOT_PASSED, FRAUD_RISK_DETECTED, AML_RISK_DETECTED. |
_REFER_FLAGS |
frozenset[str] |
BUREAU_REQUIRED_BUT_ABSENT, NO_BANKING_DATA, INSUFFICIENT_HISTORY. |
Eligibility precedence
- If any flag in
_DECLINE_FLAGSis present, the result isdecline. - If no decline flag is present but any flag in
_REFER_FLAGSis present, the result isrefer. - If neither blocking set is present and the completeness score is below
MIN_COMPLETENESS_SCORE_TO_PASS, the result isrefer. - Otherwise the result is
pass.
gate() also attaches the DataCompletenessReport to canonical.data_completeness so downstream code can reuse the computed report without recalculating it.
Component Structure
KYC Usecase Passthrough
[!NOTE]
backend/src/ml/credit_pipeline_validation.pyandbackend/src/usecase/credit_score_runtime.pyuse different bank-data missing codes. The gate emitsNO_BANKING_DATA, while runtime risk flags emitNO_BANK_DATA. These strings are not interchangeable, so any consumer comparing exact flag values must handle both names explicitly.
backend/src/usecase/kyc.py
This module is a thin use-case wrapper around KycGateway. It does not transform responses or apply underwriting logic; it simply forwards requests and returns the gateway payload.
Dependencies
| Type | Description |
|---|---|
KycGateway |
Gateway interface used to create link tokens and fetch identity verification status. |
Dict |
Return type for gateway payloads. |
Any |
Response value type from the gateway. |
Public methods
| Method | Description |
|---|---|
generate_link_token_id_verification |
Calls KycGateway.create_link_token_id_verification and returns the token payload unchanged. |
kyc_get_identity_verification_status |
Calls KycGateway.get_identity_verification_status and returns the status payload unchanged. |
Behavior
generate_link_token_id_verification(kyc_gateway, user_data)forwardsuser_datadirectly to the gateway.kyc_get_identity_verification_status(kyc_gateway, verification_id)forwards the verification identifier directly to the gateway.- The functions do not decide eligibility; they only supply or fetch identity-verification data.
Credit Pipeline Validation
backend/src/ml/credit_pipeline_validation.py
This module is the underwriting gate for completeness and compliance eligibility. It decides whether an application is safe to score, and it explicitly treats KYC, fraud, and AML flags as blocking conditions before the model can run.
Public methods
| Method | Description |
|---|---|
compute_completeness |
Builds a completeness report from canonical credit input, computes flags, and assigns pass, refer, or decline. |
gate |
Runs compute_completeness, stores the report on canonical.data_completeness, and splits blocking versus warning flags into a GatingResult. |
Observed report fields
The tests and gating flow use the following DataCompletenessReport properties:
| Property | Type | Description |
|---|---|---|
kyc_passed |
bool |
Indicates whether KYC passed for the application. |
banking_available |
bool |
Indicates whether banking data is present. |
days_covered_ok |
bool |
Indicates whether the banking history meets the minimum coverage threshold. |
salary_detected |
bool |
Indicates whether salary-like transactions were detected. |
income_verified |
bool |
Indicates whether income is considered verified from salary, bureau income, or stated income. |
bureau_available |
bool |
Indicates whether bureau data is present and usable. |
bureau_recency_ok |
bool |
Indicates whether the bureau report is fresh enough. |
completeness_score |
float |
Weighted completeness score used only after flag-based checks. |
flags |
list[str] |
Collected flags such as KYC_NOT_PASSED, AML_RISK_DETECTED, and INSUFFICIENT_HISTORY. |
gate_result |
Literal["pass", "refer", "decline"] |
Final gating decision. |
Observed gate result fields
gate() returns a GatingResult with the following fields:
| Property | Type | Description |
|---|---|---|
gate_result |
Literal["pass", "refer", "decline"] |
Final underwriting outcome. |
blocking_flags |
list[str] |
All flags that belong to the decline or refer sets. |
warn_flags |
list[str] |
Flags that do not block scoring. |
completeness_score |
float |
The computed completeness score passed through from the report. |
Eligibility flags used by the gate
| Flag | Outcome | Source behavior |
|---|---|---|
KYC_NOT_PASSED |
decline |
Added when kyc_passed is false. |
FRAUD_RISK_DETECTED |
decline |
Added when bureau fraud risk is detected. |
AML_RISK_DETECTED |
decline |
Added when bureau AML risk is detected. |
BUREAU_REQUIRED_BUT_ABSENT |
refer |
Added for products in _BUREAU_REQUIRED_PRODUCTS when bureau data is missing. |
NO_BANKING_DATA |
refer |
Added when banking data is missing. |
INSUFFICIENT_HISTORY |
refer |
Added when days covered is below MIN_DAYS_COVERED. |
BUREAU_REPORT_STALE |
warning | Added when bureau data is older than BUREAU_MAX_AGE_DAYS. |
INCOME_UNVERIFIED |
warning | Added when no salary, bureau income, or stated income can verify income. |
INCOME_STATED_ONLY |
warning | Added when only stated income is available. |
Gating behavior
KYC_NOT_PASSED,FRAUD_RISK_DETECTED, andAML_RISK_DETECTEDare treated as hard stop conditions.declinealways wins overrefer, even when missing-banking or missing-history flags are also present.gate()preserves the report on the canonical input so later steps can inspect the same completeness result.
Runtime Credit Score Scoring
backend/src/usecase/credit_score_runtime.py
This module converts application data into model features and calls the live scoring provider. It still carries KYC and AML-related signals into the feature vector, but those signals are not the pre-model eligibility decision; they are model inputs and downstream risk features after eligibility has already been resolved.
Public entry point
| Method | Description |
|---|---|
score_housing_application |
Tested runtime scoring entry point that returns a CreditScoreEstimate after feature building and provider execution. |
Internal helpers used in the scoring path
| Method | Description |
|---|---|
_score_with_vertex |
Resolves the Vertex endpoint, sends flattened features, and validates the returned prediction payload. |
_validate_risk_engine_contract |
Enforces the response contract for pd_p50_12m, pd_p90_12m, reason_codes, breakdown, and meta. |
_derive_risk_flags |
Converts model features and reason codes into post-score risk flags. |
Identity-sensitive runtime inputs
| Feature | Type | Description |
|---|---|---|
kyc_passed |
float |
Derived from application.financing_consent; 1.0 for yes, true, or 1, otherwise 0.0. |
fraud_risk_flag |
float |
Derived from bureau_payload.get("fraud_risk_flag"). |
aml_risk_flag |
float |
Derived from bureau_payload.get("aml_risk_flag"). |
bureau_available_flag |
float |
Set to 1.0 when bureau_score_value > 0. |
bureau_report_recency_days |
float |
Bureau report age propagated into the model feature set. |
bureau_parse_confidence |
float |
Parsing confidence from bureau payload. |
Post-score risk flags
_derive_risk_flags emits runtime flags based on the built feature vector and reason codes:
| Flag | Trigger |
|---|---|
NO_BANK_DATA |
accounts_linked_count == 0 |
INSUFFICIENT_HISTORY |
days_covered < 60 |
OVERDRAFT_STRESS |
Any overdraft events in the last 90 days. |
HIGH_EXTERNAL_TRANSFERS |
External transfer outflow above the configured threshold. |
HIGH_DEBT_PAYMENT_LOAD |
Debt payment burden above 35 percent of income. |
RECENT_DELINQUENCY |
Reason code indicates recent delinquency. |
MISSING_KEY_VARIABLES |
Required feature values were missing or defaulted. |
Vertex contract validation
_validate_risk_engine_contract fails closed on malformed provider responses:
pd_p50_12mmust be numeric and within0to1.pd_p90_12mmust be numeric, at leastpd_p50_12m, and at most1.reason_codesmust be a list of strings and must not exceed six values.breakdownmust contain exactly the expected keys and numeric values.meta.model_versionmust be present and string typed.
This is the runtime layer that protects the scoring path after the gate has already approved the application for model execution.
Credit Scoring Heuristic Use Case
backend/src/usecase/credit_scoring.py
This use case produces a bounded credit score estimate from application data. It is separate from the KYC and AML gate: the gate decides whether scoring is allowed, while this function determines the actual score once the application is eligible.
Public methods
| Method | Description |
|---|---|
calculate_credit_score |
Builds a CreditScoreEstimate with a bounded score, a model version, and a feature breakdown derived from the application. |
Observed scoring behavior from tests
| Behavior | Evidence |
|---|---|
Score is clamped between 300 and 850 |
test_credit_score_includes_breakdown_and_bounds, test_credit_score_clamps_extreme_inputs |
Student applications use student-open-banking-v1 |
test_student_uses_specialized_scoring, test_student_scoring_without_connected_accounts, test_student_scoring_with_good_liquidity |
Non-student applications use housing-application-heuristic-v1 |
test_credit_score_includes_breakdown_and_bounds |
Connected-account count affects connected_accounts_bonus |
test_credit_score_infers_connected_account_count_from_lists |
| Student breakdown includes open-banking risk and liquidity metrics | test_student_uses_specialized_scoring |
| Non-student breakdown includes affordability and stability metrics | test_credit_score_includes_breakdown_and_bounds |
Observed breakdown keys
| Model path | Breakdown keys |
|---|---|
housing-application-heuristic-v1 |
income_strength, savings_buffer, connected_accounts_bonus, employment_stability, affordability_penalty |
student-open-banking-v1 |
open_banking_trust, liquidity_health, behavioral_risk, savings_buffer, income_bonus, employment_stability |
Relationship to the gate
calculate_credit_score is downstream of gate(). The gate determines whether identity and compliance checks permit scoring; this function then generates the score estimate for eligible cases.
Feature Flows
Identity verification and underwriting gate
sequenceDiagram
participant App as Application Intake
participant KYC as kyc_get_identity_verification_status
participant Gateway as KycGateway
participant Gate as gate
participant Compute as compute_completeness
participant Score as score_housing_application
participant Vertex as _score_with_vertex
App->>KYC: verification_id
KYC->>Gateway: get_identity_verification_status
Gateway-->>KYC: status payload
KYC-->>App: verification status
App->>Gate: canonical credit input
Gate->>Compute: compute_completeness
Compute-->>Gate: DataCompletenessReport
alt KYC_NOT_PASSED or FRAUD_RISK_DETECTED or AML_RISK_DETECTED
Gate-->>App: decline
else BUREAU_REQUIRED_BUT_ABSENT or NO_BANKING_DATA or INSUFFICIENT_HISTORY
Gate-->>App: refer
else pass
Gate-->>App: pass
App->>Score: application
Score->>Vertex: _score_with_vertex
Vertex-->>Score: validated prediction payload
Score-->>App: CreditScoreEstimate
end
Gate evaluation order
flowchart TD
Start([gate])
Compute[compute_completeness]
DeclineCheck[Check decline flags]
ReferCheck[Check refer flags]
ThresholdCheck[Check completeness score]
Decline[decline]
Refer[refer]
Pass[pass]
Start --> Compute
Compute --> DeclineCheck
DeclineCheck -->|KYC_NOT_PASSED or FRAUD_RISK_DETECTED or AML_RISK_DETECTED| Decline
DeclineCheck -->|no decline flags| ReferCheck
ReferCheck -->|BUREAU_REQUIRED_BUT_ABSENT or NO_BANKING_DATA or INSUFFICIENT_HISTORY| Refer
ReferCheck -->|no refer flags| ThresholdCheck
ThresholdCheck -->|below minimum| Refer
ThresholdCheck -->|meets minimum| Pass
Runtime scoring contract validation
sequenceDiagram
participant Score as score_housing_application
participant Vertex as _score_with_vertex
participant Validate as _validate_risk_engine_contract
participant Risk as _derive_risk_flags
Score->>Vertex: flat features
Vertex->>Validate: prediction object
Validate-->>Vertex: _RiskEngineOutput
Score->>Risk: features and reason_codes
Risk-->>Score: runtime risk flags
State Management
The gate is modeled as a three-state underwriting outcome: pass, refer, and decline. The state is derived deterministically from completeness flags and the completeness score, and gate() stores the report back on the canonical input as canonical.data_completeness.
stateDiagram-v2
[*] --> Evaluate
Evaluate --> Decline: KYC_NOT_PASSED or FRAUD_RISK_DETECTED or AML_RISK_DETECTED
Evaluate --> Refer: BUREAU_REQUIRED_BUT_ABSENT or NO_BANKING_DATA or INSUFFICIENT_HISTORY
Evaluate --> Pass: completeness_score meets minimum
Decline --> [*]
Refer --> [*]
Pass --> [*]
Gate outcome meaning
decline: underwriting stops before model execution.refer: the application needs manual review or additional data.pass: the application may proceed to scoring.
Integration Points
src.ml.credit_canonical_schemaprovidesCanonicalCreditInput,CanonicalBureauData,CanonicalOpenBankingData,CanonicalTransaction, andDataCompletenessReport.src.domain.kyc_gateway.KycGatewaysupplies identity verification status and link-token creation.- Vertex AI is used in the runtime scoring path through
aiplatform.Endpoint. - Environment variables control both gating thresholds and runtime provider resolution.
Runtime and gating environment variables
| Variable | Used in | Purpose |
|---|---|---|
PIPELINE_MIN_DAYS_COVERED |
credit_pipeline_validation.py |
Minimum banking history coverage. |
PIPELINE_BUREAU_MAX_AGE_DAYS |
credit_pipeline_validation.py |
Bureau freshness threshold. |
PIPELINE_MIN_COMPLETENESS_SCORE |
credit_pipeline_validation.py |
Minimum fallback completeness score. |
PIPELINE_BUREAU_REQUIRED_PRODUCTS |
credit_pipeline_validation.py |
Products that require bureau data. |
PROJECT_ID |
credit_score_runtime.py |
Vertex project identifier. |
REGION |
credit_score_runtime.py |
Vertex region. |
VERTEX_CREDIT_ENDPOINT_ID |
credit_score_runtime.py |
Endpoint identifier used to resolve the prediction endpoint. |
LITA_HOST_COUNTRY |
credit_score_runtime.py |
Host-country feature default. |
LITA_CORRIDOR_CLUSTER_ID |
credit_score_runtime.py |
Corridor grouping feature. |
LITA_HOST_UNEMPLOYMENT_RATE |
credit_score_runtime.py |
Macroeconomic feature. |
LITA_HOST_INFLATION_RATE |
credit_score_runtime.py |
Macroeconomic feature. |
LITA_HOST_INTEREST_RATE_PROXY |
credit_score_runtime.py |
Macroeconomic feature. |
Error Handling
credit_pipeline_validation.py uses deterministic flag evaluation and does not rely on exceptions for normal gate outcomes. The relevant error states are expressed as decline or refer, which makes eligibility decisions explicit and testable.
credit_score_runtime.py is stricter at the provider boundary. _validate_risk_engine_contract raises ValueError when the provider response does not match the required contract, and test_vertex_provider_fails_closed_on_invalid_contract confirms the failure path.
credit_scoring.py clamps the score into the supported range, which prevents out-of-bounds scores from escaping into downstream consumers.
Testing Considerations
Gate regression coverage
| Test class | Methods | Coverage |
|---|---|---|
TestDeclineGates |
test_kyc_not_passed_gives_decline, test_fraud_flag_gives_decline, test_aml_flag_gives_decline, test_decline_takes_priority_over_refer |
Confirms that KYC, fraud, and AML flags force decline, and that decline overrides refer conditions. |
TestReferGates |
test_no_banking_data_gives_refer, test_insufficient_history_gives_refer, test_exactly_min_days_covered_does_not_refer_on_history, test_high_ticket_loan_without_bureau_gives_refer, test_regular_product_without_bureau_does_not_require_bureau |
Confirms refer behavior for missing banking, short history, and bureau-required products. |
TestPassGate |
test_full_data_passes, test_pass_without_bureau_for_rental |
Confirms that valid applications can pass even when bureau data is absent for non-required products. |
TestCompletenessScore |
test_full_data_gives_score_above_threshold, test_score_is_near_zero_when_nothing_available, test_score_bounded_between_0_and_1, test_adding_bureau_increases_score |
Confirms score weighting and range behavior. |
TestBureauAvailability |
test_bureau_available_true_when_score_present, test_bureau_available_false_when_score_zero, test_bureau_available_false_when_none, test_stale_bureau_adds_flag, test_fresh_bureau_no_stale_flag |
Confirms bureau presence and recency classification. |
TestIncomeDetection |
test_salary_category_detected, test_payroll_category_detected, test_non_income_category_not_detected_as_salary, test_income_verified_via_stated_income, test_income_verified_via_bureau_income, test_income_unverified_when_nothing_present |
Confirms salary detection, income verification, and warning flags. |
TestGateFunction |
test_gate_attaches_report_to_canonical, test_gate_separates_blocking_and_warn_flags, test_gate_result_decline_returned_correctly, test_gate_result_pass_returned_correctly, test_gate_completeness_score_populated |
Confirms gate() side effects and result shaping. |
Runtime scoring tests
| Test file | Scenario |
|---|---|
backend/tests/usecase/test_credit_scoring.py |
Verifies score bounding, model version selection, breakdown keys, connected-account inference, and student-specific behavior. |
backend/tests/usecase/test_credit_score_runtime.py |
Verifies Vertex-backed scoring, response contract validation, and fail-closed behavior on invalid provider payloads. |
Key Classes Reference
| Class | Responsibility |
|---|---|
kyc.py |
Passes identity-verification requests through to KycGateway without altering the returned payload. |
credit_pipeline_validation.py |
Computes completeness and blocks or routes underwriting before any model execution. |
credit_score_runtime.py |
Builds runtime features, validates provider output, and emits post-score risk flags. |
credit_scoring.py |
Produces bounded heuristic credit estimates and breakdowns for eligible applications. |
test_pipeline_validation.py |
Verifies gate priority, completeness scoring, bureau freshness, and income detection behavior. |
test_credit_scoring.py |
Verifies score model versioning, bounds, and feature breakdown construction. |
test_credit_score_runtime.py |
Verifies runtime provider contract enforcement and Vertex-backed execution. |