Customer Onboarding KYC Verification

Four request objects feed the checks: customer (address country, isPoliticallyExposed, isHighRiskBusiness), financialInfo with the estimatedTransactionValue, verification carrying the identity document details, and watchlist with pre-computed sanctions, PEP, and adverse media match flags.

Risk is scored on four inputs with a first hit policy. Customers from the low-risk country list ('US', 'CA', 'GB', 'AU', 'NZ', 'JP', 'DE', 'FR') with no PEP or business flags score 10 'low' under 10000 of estimatedTransactionValue and 30 'medium' up to 100000; a PEP from those same countries jumps to 75 'high' and a high-risk business to 70. Any customer from the 'RU', 'IR', 'KP', 'CU', 'SY', 'VE' list scores 100 'very-high' regardless of other fields, combined PEP and high-risk business status elsewhere scores 90, transactions of 100000 or more score 60, and the fallback is 40 'medium'.

This is the risk-based approach FATF guidance expects, where geography, customer type, and transaction size each move the rating. Treating PEPs as high risk regardless of transaction value follows FATF Recommendation 12, and the very-high country list corresponds to jurisdictions under comprehensive sanctions programs; the specific 10000 and 100000 breakpoints are the institution's own calibration.

Acceptance depends on both the document and the risk it must support: a valid 'passport' verifies every tier, producing 'standard' verification at 'low' or 'medium' risk and 'enhanced' with extra checks at 'high' or 'very-high'; a 'driving_license' only verifies 'low' risk customers and comes back 'insufficient' above that, while a 'national_id' covers 'low' and 'medium'. Any document with status 'expired', 'damaged', or 'suspicious' is 'rejected' outright, and the final catch-all marks the case 'missing'.

Tiering documents this way reflects their assurance value in customer due diligence: passports are government-issued, internationally standardized, and hardest to forge, so they anchor the higher tiers, while a driving licence is acceptable evidence only where exposure is small. The exact pairings of document type to risk level are the firm's own policy choice, but demanding stronger identity evidence as risk rises is the substance of a risk-based CDD program.

Screening outcomes cascade in severity order under a first hit policy: sanctionsMatch true immediately returns 'reject' with 'Customer appears on sanctions list', a pepListMatch or adverseMediaMatch each return 'review' for manual handling, and a clean result across all three passes with 'No watchlist hits found'.

The asymmetry is deliberate and mirrors real compliance obligations: a sanctions hit cannot be risk-managed, since dealing with sanctioned persons is prohibited, so it hard-blocks onboarding. PEP status and adverse media are not prohibitions under FATF guidance, they are triggers for enhanced scrutiny, which is why those rows route to human review instead of rejection.

Two booleans set up the tier: requiresEDD fires when assessment.riskLevel is 'high' or 'very-high' or the watchlist came back 'review', and isSanctioned mirrors a watchlist 'reject'. The nested ternary then resolves dueDiligenceLevel to 'blocked', 'enhanced', or 'standard', the single value the requirements table keys on next.

Verification obligations scale with the tier: 'enhanced' due diligence with a riskScore of 60 or more switches on all four requirements (sourceOfFunds, addressVerification, faceVerification, enhancedMonitoring), while 'enhanced' below 60 drops only faceVerification. 'standard' customers need addressVerification when their score is 40 or above and nothing extra below that, and the 'blocked' row returns false across the board since no verification can cure a sanctions match.

Collecting source of funds and applying ongoing monitoring for enhanced-tier customers matches the enhanced due diligence measures FATF and national AML rules describe for higher-risk relationships, including PEPs. Graduating the burden keeps onboarding friction proportional: low-risk applicants clear with baseline document checks, which is the cost-control argument for risk-based compliance.

Everything converges into a final verdict: verificationStatus resolves to 'rejected' when dueDiligenceLevel is 'blocked', 'approved' when the document verified and the watchlist passed, and 'pending' otherwise. Alongside it, requiredActionsCount counts the true flags in requirements with count(values(requirements), # == true), and nextSteps renders the matching operator instruction, so the caller gets a decision plus a work queue in one payload.