Authenticate with biometrics
Beta
Last updated: June 4, 2025
The Face Authentication solution enables you to confirm that an applicant requesting to access new services or an existing account is the same person whose identity you've successfully verified.
Information
To enable Face Authentication, contact your account manager or [email protected].
- You must have already integrated the Identity Verification solution and verified the applicant.
- The applicant must already have a profile.
- You must have a non-anonymized face video from a previous successful identity verification or face authentication available for the applicant.
- Prepare to handle statuses, attempts, and response codes.
- Set up your webhook receiver and prepare to handle webhooks.
When you request to enable Face Authentication, your account manager provides you a configuration ID, prefixed with usj_.
This is different to your Identity Verification configuration ID.
You must provide the ID every time you create an authentication. It configures the following elements of the solution:
- The service level agreement for receiving the result from Checkout.com
- How long to retain verification face videos to ensure you have one available for authentications
- Processing type:
- Auto – Fully automated processing
- Expert – Systematic human review
The applicant captures a video of their face. Checkout.com compares the biometrics to a previous video of the applicant to check if they show the same person, and shares the result.
Follow these steps:
- Create an authentication linked to the applicant's profile.
- Create an attempt and redirect the applicant.
- Retrieve the authentication to see the result.
Call the Create a face authentication endpoint, and provide the following fields:
applicant_id– The applicant IDuser_journey_id– Your Face Authentication configuration ID
post
https://identity-verification.sandbox.checkout.com/face-authentications
The response returns the authentication ID in the id field, prefixed with fav. You need this to create an attempt.
The authentication status changes to created and you receive a Face authentication created webhook.
Call the Create an attempt endpoint, and provide the authentication ID from the Create an authentication response as the {face_authentication_id} path parameter.
Provide the following fields in the request body:
redirect_urlfield – Provide the URL to redirect the applicant to after they complete the authentication.phone_numberobject – If you want to send the applicant the attempt URL via SMS, provide their phone number.client_information.pre_selected_residence_countryfield – If you want to provide the applicant's country of residence, you can use this field. This shortens the verification journey and improves the experience because they do not have to select their country manually.
post
https://identity-verification.sandbox.checkout.com/face-authentications/{face_authentication_id}/attempts
The response returns:
- The attempt ID in the
idfield, prefixed withfatp - The attempt URL in the
verification_urlfield - The attempt status
pending_redirection
The authentication status changes to pending and you receive a Face authentication opened webhook.
Redirect the applicant to the attempt URL, which is valid for 15 minutes.
Note
If an attempt is unsuccessful and the applicant needs to retry, you can create new attempts.
We recommend sharing guidance from the response codes returned in webhooks to help the next attempt succeed. For example, if the applicant's data connection is poor, let them know so they can try to improve it.
The following table describes the process of a successful attempt:
A successful attempt proceeds as follows:
| Step | Description |
|---|---|
Applicant starts the attempt | The authentication and attempt statuses change to You receive a Face authentication started webhook. When successfully completed, the attempt status changes to You receive a Face authentication capture completed webhook. |
Checkout.com processes the authentication | The authentication status changes to When processing is complete, you receive a Face authentication checks completed webhook. You may receive the checks completed webhook simultaneously with the capture completed webhook. |
Result is available | The authentication status changes to either If the applicant is declined, you can create a new authentication. |
You can manage attempts using the following endpoints:
- List attempts – Retrieve all attempts for an authentication.
- Retrieve an attempt – Retrieve the details about a specific attempt.
You can retrieve the authentication at any time. For example, to check the status or details about an attempt. When the result is available, it is returned in the response.
Call the Retrieve a face authentication endpoint, and provide the authentication ID as the {face_authentication_id} path parameter.
get
https://identity-verification.sandbox.checkout.com/face-authentications/{face_authentication_id}
The response returns:
- The authentication status
- One or more response codes
- A URL to download a still from the face video, if the result is available
If an applicant requests that you remove their personal data under the GDPR, you can use the Anonymize a face authentication endpoint.
You receive an Face authentication anonymized webhook.
If the authentication is later audited and the status updated, you receive an Face authentication audit completed webhook.