Fintech Development

KYC/AML Integration Failure Handling Prompt

Integrate a third-party KYC/AML verification API and design graceful handling for its pending, failed, and ambiguous verification states.

Anselm Fowel / Public collection28 Sept 2026

Your prompt

The prompt

You are a fintech engineer who has integrated KYC/AML verification providers into onboarding flows and knows these APIs are asynchronous, occasionally slow, and never return a clean binary answer.

I'm integrating [KYC/AML PROVIDER: PERSONA / ALLOY / ONFIDO / JUMIO] into an onboarding flow built in [LANGUAGE/FRAMEWORK] for [USER TYPE: INDIVIDUAL CONSUMERS / SMALL BUSINESSES]. Verification results can come back as [POSSIBLE STATUSES IF KNOWN, e.g., APPROVED / REJECTED / PENDING MANUAL REVIEW / ADDITIONAL INFO REQUIRED].

First, design the state machine for a user's verification status end to end, including what state the user account is in immediately after submission, while the provider is processing asynchronously, and after each possible terminal or semi-terminal outcome. Specify what the user can and cannot do (e.g., view-only access vs. full access vs. blocked) at each state.

Next, design the webhook or polling integration that receives the provider's result, including how you handle the provider's callback arriving out of order relative to a user re-submitting corrected documents, and how you avoid a race where two verification attempts for the same user create conflicting status updates.

Then design handling for the provider's own failure modes: the API times out, returns a 5xx, or is down entirely during a compliance-critical moment (account opening, large transaction requiring step-up verification). Specify whether the system fails closed or open in each case and why that choice is defensible from a compliance standpoint, not just an availability one. Also address the ambiguous "pending manual review" and "additional info requested" states: how long a user can sit there, what triggers a re-check or escalation, and what's logged for audit purposes given regulators will ask to see exactly why a user was approved or denied.

Finally, output the full state machine as a diagram described in text, the webhook handler in [LANGUAGE/FRAMEWORK] with comments, and a table mapping each provider failure mode to system behavior and compliance justification.

2,089 characters

Your prompt

Recent articles