Customer KYC & Document Verification

LedgerFlow supports five distinct regulatory verification programmes, each configured independently with its own document requirements and country-specific policies:

• KYC — Know Your Customer: identity and address verification for natural persons
• KYB — Know Your Business: corporate registration, ownership structure, and UBOs for legal entities
• KYM — Know Your Merchant: trading licence, bank account, and risk profile for merchants
• KYT — Know Your Transaction: behavioural and transactional due diligence (links to the fraud engine)
• CDD — Customer Due Diligence: enhanced verification for higher-risk relationships

Each programme maps to verification tiers (Basic, Standard, Enhanced) stored in journal.document_kyc_requirement_tiers_docs. Country-level overrides in journal.document_kyc_country_codes let compliance teams tailor requirements per jurisdiction without changing code.

The same engine drives both the staff compliance dashboard and the customer self-service portal, giving operators a single source of truth for every entity's verification status.

The diagram shows the full state machine for a KYC or KYB process. A pg_timetable scheduler job initiates each process, sends the invitation email, and tracks every subsequent state change with a full audit trail.

Automated reminder cycles — if a customer has not uploaded within the configured window (default 7 days), a reminder is sent automatically. A maximum of 3 reminder rounds are attempted before the process transitions to Expired. Staff can issue a manual reminder at any point.

Branch outcomes at Under Review: the compliance officer either approves (KYC status updated on the user or entity record), rejects (reason recorded, customer notified), or requests additional documents (process resets to In Progress). The dblink mechanism ensures status updates persist even if the reviewing transaction is rolled back.

Standard KYC collects and validates documents that prove identity and residential address for natural persons — customers, beneficial owners, and authorised signatories.

Typical document requirements (configurable per country):

Documents are uploaded through the customer self-service portal, processed by the Docling OCR pipeline for metadata extraction, and assigned a SHA-256 content hash that is stored alongside the document record. Expiry dates are tracked; the scheduler flags and re-initiates processes when existing documents approach expiry.

KYB and KYM programmes verify the corporate identity of legal entities and merchants registered on the platform. This covers PSPs, sub-merchants, vendors, and corporate customers.

KYB typically requires:

• Certificate of Incorporation / Company Registration
• Memorandum and Articles of Association
• Register of Directors and Shareholders
• UBO (Ultimate Beneficial Owner) declarations
• Recent bank statements or audited accounts

KYM adds:

• Trading licence
• Payment method agreements
• Acquiring bank details
• Risk category classification

Entity verification status is tracked on the api.customers table (kyc_status, kyc_tier columns) and surfaced through the customer management UI with full document history.

Every KYC requirement set is classified into one of three tiers, each representing a progressively higher level of regulatory scrutiny. The appropriate tier is determined by customer risk classification and jurisdictional rules.

Basic — Entry-level verification. Accepts a single primary ID document. Suitable for low-value, low-risk relationships and prepaid product categories.

Standard — Full identity plus address confirmation. The default tier for most retail customers and SME merchants. Requires at least two documents from different categories.

Enhanced — Comprehensive due diligence for high-risk, high-value, or politically-exposed relationships. May require additional source-of-funds evidence, independent reference checks, or manual risk committee sign-off.

Tier assignments are stored in journal.document_kyc_requirement_tiers_docs and can be overridden per country via journal.document_kyc_country_codes.

The KYC scheduler runs daily via pg_timetable and manages the full invitation lifecycle without manual intervention:

1. Detect — Identifies users and entities requiring verification (new registrations, tier upgrades, expiring documents)
2. Invite — Sends a personalised email with a secure upload link; sets process status to invited
3. Remind — After the configured grace period (default 7 days), sends a reminder if no documents received
4. Escalate — Up to 3 reminder rounds; each reminder is logged with a timestamp
5. Expire — If no response after 3 rounds, transitions to expired and notifies the compliance team
6. Renew — For existing approved customers, proactively initiates renewal when documents approach expiry

All transitions are recorded in api.kyc_process with a full status history. The scheduler is idempotent — safe to re-run at any frequency.

When a customer uploads a document, LedgerFlow enqueues it to the journal.kyc_docling_queue for processing by the Docling API — a self-hosted document intelligence service that performs OCR, structure extraction, and metadata parsing.

Processing pipeline:

1. Customer uploads document through self-service portal
2. Document binary is stored; SHA-256 content hash is computed and recorded
3. Docling job is enqueued (serialised — no concurrent Docling calls to respect rate limits)
4. Docling returns extracted text, detected language, document type classification, and expiry date (where present)
5. Extracted metadata is stored alongside the document record
6. Staff reviewer sees both the original document and the extracted data side-by-side

Integrity guarantees: The SHA-256 hash is stored at upload time and re-verified before each Docling submission. Any content modification between upload and processing is detected and flagged. Document hashes provide a cryptographically verifiable chain of custody from upload through to compliance approval.