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

  1. If any flag in _DECLINE_FLAGS is present, the result is decline.
  2. If no decline flag is present but any flag in _REFER_FLAGS is present, the result is refer.
  3. If neither blocking set is present and the completeness score is below MIN_COMPLETENESS_SCORE_TO_PASS, the result is refer.
  4. 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.py and backend/src/usecase/credit_score_runtime.py use different bank-data missing codes. The gate emits NO_BANKING_DATA, while runtime risk flags emit NO_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) forwards user_data directly 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, and AML_RISK_DETECTED are treated as hard stop conditions.
  • decline always wins over refer, 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_12m must be numeric and within 0 to 1.
  • pd_p90_12m must be numeric, at least pd_p50_12m, and at most 1.
  • reason_codes must be a list of strings and must not exceed six values.
  • breakdown must contain exactly the expected keys and numeric values.
  • meta.model_version must 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_schema provides CanonicalCreditInput, CanonicalBureauData, CanonicalOpenBankingData, CanonicalTransaction, and DataCompletenessReport.
  • src.domain.kyc_gateway.KycGateway supplies 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.