Identity verification (KYC/KYB) is the gatekeeper of fintech. Technically, it is an asynchronous workflow that interrupts the user journey. You cannot await a KYC response like a database query; it may take 5 seconds (AI check) or 5 days (Manual Review). The architecture must handle these long-running states without blocking the user interface or losing the context of the signup.
The State Machine Integration
The user entity needs a dedicated verification_status state machine:
unverified: Default state. Restricted access.
pending_check: Docs uploaded, waiting for provider webhook.
approved: Webhook received with decision: accept. Limits lifted.
manual_review: Provider flagged ambiguity. Operations team alerted.
rejected: Final terminal state. Offboarding triggers.
Critical Logic: The payment endpoints must have middleware checking if status == approved before allowing money movement.
Webhook Security and Race Conditions
KYC providers notify success via webhooks.
Signature Verification: You must verify the provider's HMAC signature to ensure the "Approved" signal isn't faked by an attacker.
Race Conditions: If a user is rejected but the webhook is delayed, they might slip a transaction through. Best practice is to query the status at the moment of transaction (synchronous check) for high-risk actions, rather than relying solely on the cached status from the webhook.
