Document check

In a KYC session, only an identity document can approve the person. This page follows the person through the document path and explains what decides the result. The parts shared with age verification (the start screen on phones and computers, languages, browser and camera requirements, and how the person returns to your site after a success) are described in Verification flow.

A KYC session is a session created with force_kyc: true and force_verification: true, or a session started from a device that has Force KYC Verification on. See Integrating KYC.

Before you send the person

• Tell them they need their document. The start screen talks about a short liveness check and does not mention a document. Before you send the person, tell them they will need their physical identity document and a device with a camera.
• Give the session enough time. expiration_time counts from the moment you create the session and has to cover both the face scan and the document scan. The default is 300 seconds. For a KYC session, consider 600 or more (the maximum is 3600).
• Open verify_url as a top-level page, not inside an iframe. See Browser and camera requirements.

Step by step

1. Start screen. On a phone or tablet, the person taps Verify Now. On a computer, the page asks for the webcam; without one, the person scans the QR code (No camera? Scan with your phone) and continues on the phone.
2. Face scan. The scanner opens inside the page and guides the person to place their face in an oval. It checks that a real person is in front of the camera. The photo on the document is compared with this scan, so it always comes first. The scan also produces an age estimate, as the notice on the start screen says, but in a KYC session that estimate can neither approve nor reject. The status becomes verification_started and validation.biometry_started is sent.
3. Document notice. The page shows "Document verification is required" and "Please have your ID document ready for scanning". About a second later, the document scanner opens.
4. Document scan. The scanner guides the person to photograph the front of their identity document and, when it asks for it, the back. It can ask them to take a side again. When the document scan starts, the status becomes verification_kyc and validation.kyc_started is sent.
5. Result. After a short transition of a few seconds, the page shows the success screen or the failure screen.

When a scan does not finish, there is no result:

What decides pass or fail

The face scan never decides a KYC session. The document decides it, and it passes only when all of these hold:

• it is recognized as a physical document;
• the photo on the document matches the face scan from the same session;
• the person's age, in whole years, is at least your age_target.

The age comes from the date of birth read from the document. When the date of birth cannot be read, the check can currently use an age estimate made from the photo on the document instead, compared with your age_target. With no date of birth and no estimate to use, the document is rejected.

Those conditions are the whole rule. It has no condition on the name on the document, its expiry date, its type or the country that issued it. If your process requires checks like these, the result of a Bouncer KYC session does not provide them.

When a document fails any condition, the session becomes completed with success: false, and validation.completed is sent. The failure screen does not say which condition failed, and no documented field gives the reason. Bouncer also adds a facetec block to metadata. That block is reserved: its content is not part of the API contract and can change, so do not build logic on it.

After a rejected document

The person sees We couldn't verify your age, with no reason, and two options:

• Verify age with your ID starts again in the same session: a new face scan, then a new document scan. The status goes back to verification_started while success stays false, and validation.biometry_started and validation.kyc_started are sent again.
• Try the validation again works differently by session type. For an API session, it opens the same session, which shows the failure screen again. For a device session, it starts a new session through the device's entry screens.

A rejection does not lock the session. If a later document passes, the session becomes completed with success: true, and a second validation.completed is sent. So success: false is not final while the session is open. See Results.

There is no redirect after a failure. The person stays on the Bouncer page. Learn about the failure from the webhook or with GET /api/v2/session/{id}, and offer the next step from your side. If your own page is still open (for example, you opened the check in a new tab), let it poll so it can show that step.

Attempts and limits

• There is no attempt limit for you to configure. What limits the attempts is the session's lifetime: once expires_at has passed, no new scan can start.
• The person can repeat a face scan that gave no result, and can try another document after a rejection, as many times as the session's lifetime allows.
• Retries inside a session keep the same id, and each document result sends its own validation.completed. The exception is Try the validation again in a device session, which starts a new session with a new id.
• After expiry, the only way to try again is a new session.

Expiry

• After expires_at, the page shows Session expired with a Start a new session button ("You will start over"). For an API session, the button opens the same expired session again, so the person cannot get back to your site from there: offer a new session from your side. For a device session, it goes back to the device's entry screens and a new session.
• A scan step that reached Bouncer before expires_at can still be decided after it. The session then ends completed, with success true or false, after expires_at, and validation.completed is sent. Meanwhile the person may see Session expired and is not redirected. Always check the result on your server.
• Nothing is written when the time runs out: there is no expired status and no expiry webhook. See Sessions.

Device sessions

• Turn on Force KYC Verification on a device to make every session started from it a KYC session. Device sessions always require a scan, so the re-verification shortcut never applies to them.
• Set the device's Age Target. A device without one checks against 18.
• Give the device a Session Expiration of 10 minutes or more, for the same reason as expiration_time above.
• A session started from the device's fixed QR code or permanent link goes through the device's entry screens before the steps above.
• The events before the result (validation.biometry_started, validation.kyc_started) reach you only when the device has Send all events on. validation.completed is always sent.
• See Devices.