Build a KYC Passport + Liveness Detection UI on iOS

What a KYC liveness flow actually does

A KYC passport and liveness flow has three parts, and only two of them are UI. First, the user captures their identity document, a passport or ID, which a verification service reads, often from the machine-readable zone. Second, the user passes a liveness check, the face-in-circle moment where they position their face and follow prompts so the system can confirm a real, present person rather than a photo or a video. Third, and crucially, a certified identity provider verifies that the face matches the document and that the liveness was genuine. The first two are screens you build; the third is a regulated service you integrate, and confusing the two is where most KYC projects go wrong.

So the project is not “detect liveness.” It is “guide the capture well and hand it to a provider that does the verification.” That distinction shapes every decision below.

The rule that shapes everything: do not build liveness yourself

The most important thing to know about a liveness flow is that you should not build the liveness detection yourself. Proving that a face is a real, present person and not a printed photo, a screen replay, or a deepfake is an adversarial anti-spoofing problem that dedicated providers spend years and large teams on, and it is increasingly tied to regulatory standards for identity verification under KYC rules. A homegrown check that looks for a blink or a head turn is trivially defeated by a video, so rolling your own is both ineffective and a compliance risk. The right architecture is to integrate a certified identity provider’s SDK, which performs the liveness and the document match, while you build the capture UI around it.

This is liberating once accepted. You are not responsible for solving anti-spoofing; you are responsible for a clear capture experience that feeds a provider built and certified to do the hard part.

The face-in-circle UI is capture guidance, not verification

The face-in-circle that people associate with liveness is a guidance UI, not the verification itself. Its job is to help the user position their face well so the provider gets a usable capture: a circular cutout showing where the face should go, real-time prompts like move closer, hold still, or turn slightly, and clear feedback when the framing is right. On iOS, Vision can detect a face and its position to drive those prompts, and AVFoundation runs the camera, but neither proves liveness, they just make the capture good enough for the provider to evaluate. It helps to be clear about the gap: device biometrics like Face ID are extremely accurate at recognizing a phone’s owner, with a roughly 1 in 1,000,000 false-match rate, but that authenticates an existing enrollment on a trusted device, which is a different problem from proving a new user’s identity, the job KYC liveness does through a provider.

So the circle, the prompts, and the framing feedback are yours to design, and they matter for completion rates, but they are presentation. The proof happens in the provider, off the device.

The approaches compared

There are three realistic ways to do the liveness piece, and they differ sharply in risk.

Approach	Anti-spoofing reliability	Customization	Effort and risk
Build your own liveness detection	Weak, spoofing is hard to stop and easy to defeat	Full	High effort, high compliance risk, not advised
Certified provider SDK with your own capture UI	Strong, the provider handles it	High, you design the circle and prompts	Medium
Provider’s drop-in UI	Strong	Low, the provider’s look and feel	Low

Building your own is the option to avoid, because it neither stops real attacks nor satisfies the certification that regulated onboarding needs. A provider’s drop-in UI is the fastest path but gives you their look, which can feel off-brand in the middle of your flow. Wrapping a certified provider’s SDK with your own capture UI is the balance most serious apps want: the provider does the verification and the anti-spoofing, and you control the document screen, the face-in-circle, and the states so the flow feels like your app. A free VP0 KYC liveness template starts you on that capture UI, with the document-capture screen, the circle overlay, the prompts, and the states already shaped and exposed through a machine-readable source page, so an agent like Cursor or Claude Code extends a polished capture flow and you wire the certified provider’s SDK behind it. The surrounding verification screens share patterns with a fintech KYC verification UI and a BVN verification input screen.

What a KYC liveness template needs

A complete capture template covers the whole flow with its real states. It needs a document-capture screen that frames the passport or ID and guides the user to fill the frame and avoid glare, a liveness screen with the circular cutout and the live prompts, and clear states throughout: face not detected, too far or too close, poor lighting, hold still, captured, and a failure state that lets the user retry rather than dead-ends. It also needs explicit consent before any capture, because biometric data is sensitive, and a clear explanation of why the verification is needed. The selfie-capture pattern overlaps an employee time-clock selfie verification UI.

The states are where completion rates live. A capture flow that leaves a user guessing why their face will not register, or that fails without a retry, loses people at the most sensitive moment of onboarding.

Handling biometric data responsibly

Biometric data is among the most sensitive personal information there is, and a KYC flow has to treat it that way. The honest architecture keeps the verification, and the biometric data, with the certified provider rather than in your app: the capture is handed to the provider’s SDK, which performs the check and holds the data under its compliance regime, and your app does not store raw face images or document scans it does not need. Consent is explicit and informed before capture, the user is told what is collected and why, and the flow complies with the privacy law of the market, such as GDPR or CCPA. Treating biometric capture casually, storing selfies in your own bucket, is exactly the liability the provider architecture exists to avoid.

The app guides the capture and presents the result; the regulated handling of the biometric data and the proof of identity belong to the certified provider.

Key takeaways: a KYC passport and liveness UI

• Three parts, two are UI. Document capture and the liveness circle are yours; the verification is a provider’s.
• Do not build liveness yourself. Anti-spoofing is hard and regulated, so wrap a certified provider’s SDK.
• The face-in-circle is guidance. Vision and the camera frame the capture; they do not prove liveness.
• Handle biometric data through the provider. Explicit consent, no casual storage, and compliance with privacy law.
• Start from a capture template. A free VP0 KYC liveness template gives an agent the document and circle UI to wire a provider into.

What to choose

For a KYC passport and liveness flow, build the capture UI from a template and integrate a certified identity provider for the verification, because the anti-spoofing and the regulated proof of identity are the provider’s job, not yours. A free VP0 KYC liveness template gives you the document-capture screen, the face-in-circle, the prompts, and the states, so an agent extends a polished capture flow and you wire the provider’s SDK behind it, with explicit consent and the biometric data kept with the provider. A provider drop-in UI is the fastest path if you can accept their look, and building your own liveness detection is the one approach to avoid, since it neither stops attacks nor satisfies certification.

Frequently asked questions

How do I build a KYC passport and liveness detection UI for iOS? Build the capture experience and integrate a certified provider for the verification. The UI you build is a document-capture screen that frames the passport or ID, and a liveness screen with a circular face cutout and live prompts like move closer or hold still, driven by Vision for face position and AVFoundation for the camera. The actual liveness verification and document match are done by a certified identity provider’s SDK, which you wire behind the capture. A free KYC liveness template gives you the document screen, the circle overlay, the prompts, and the states to start from.

Should I build my own liveness detection? No. Proving a face is a real, present person rather than a printed photo, a screen replay, or a deepfake is an adversarial anti-spoofing problem that certified providers specialize in, and it is tied to regulatory standards for identity verification. A homegrown blink-or-turn check is easily defeated by a video and does not satisfy compliance. The right approach is to integrate a certified identity provider’s SDK for the liveness and document match, while you build the capture UI around it. That keeps the hard, regulated part with a provider built for it.

Where can I get a KYC liveness or passport capture UI template? The most useful option is a template for the capture flow you wrap around a provider, not a verification engine. A free VP0 KYC liveness template provides the document-capture screen, the face-in-circle, the prompts, and the states, with a machine-readable source page, so an agent like Cursor or Claude Code extends a polished capture UI. You then integrate a certified identity provider’s SDK for the verification and keep the biometric data with the provider, since the template is the capture interface and the regulated proof is the provider’s. It is built for clear guidance and honest states rather than the anti-spoofing itself.

Is the face-in-circle the actual liveness check? No, the face-in-circle is a guidance UI that helps the user position their face so the provider gets a usable capture. It shows where the face should go and gives prompts like move closer or hold still, using on-device face detection to drive the feedback, but it does not prove liveness by itself. The real anti-spoofing and the match between the face and the document happen in a certified identity provider, off the device. The circle improves completion rates and capture quality; the proof is the provider’s job.

How should a KYC app handle biometric data? With great care, because biometric data is among the most sensitive personal information there is. The responsible architecture keeps the verification and the biometric data with the certified provider rather than in your app: the capture is handed to the provider’s SDK, which performs the check and holds the data under its compliance regime, and your app does not store raw face images or document scans it does not need. Consent is explicit and informed before capture, and the flow complies with the relevant privacy law, such as GDPR or CCPA. Storing biometric captures casually is the liability the provider architecture exists to avoid.