Authenticate with biometrics using the API
Beta
Last updated: January 21, 2026
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.
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.
Information
To enable Face Authentication, contact your account manager or request support.
- You must have already integrated the Identity Verification solution and verified the applicant.
- The applicant must already have a profile and an applicant ID, prefixed with
aplt_. - You must have a non-anonymized face video from a previous successful identity verification or face authentication available for the applicant.
- Handle statuses, attempts, and response codes.
- Subscribe to Face Authentication webhooks.
When you request to enable Face Authentication, your account manager provides you a Face Authentication 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
- Retrieve the applicant ID.
- Create an authentication linked to the applicant's profile.
- Create an attempt.
- Redirect the applicant to the attempt.
- View the authentication result.
- If requested, you can remove the applicant's personal details from the authentication.
Call the Create a face authentication endpoint, and provide the following fields:
applicant_id– The applicant ID.user_journey_id– The relevant Face Authentication configuration ID.
post
https://identity-verification.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 a face authentication attempt endpoint, and provide the authentication ID as the {face_authentication_id} path parameter.
In the request body, provide the following fields:
redirect_url– The URL to redirect the applicant to after they complete the authentication. For example, your success or failure URL.client_information.pre_selected_residence_country– Optionally, the applicant's country of residence.client_information.pre_selected_language– Optionally, the language to use for the user interface.
Information
Providing the applicant's country of residence shortens the authentication journey and improves the experience because they do not have to select their country manually.
post
https://identity-verification.checkout.com/face-authentications/{face_authentication_id}/attempts
The response returns:
- The attempt ID in the
idfield, prefixed withfatp_ - The attempt URL, which is valid for 15 minutes, in the
verification_urlfield
The attempt status changes to pending_redirection and the authentication status changes to pending.
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.
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. |
Information
You can use the response codes returned in webhooks to implement your own business logic. Sharing guidance from response codes with the applicant can help the next attempt succeed. For example, if the applicant's data connection is poor, inform them so they can try to improve it.
You can retrieve face authentication attempts using the following endpoints:
- Get face authentication attempts – Retrieve all attempts for an authentication.
- Get a face authentication attempt – Retrieve the details for a specific attempt.
You can view the face authentication at any time. For example, to check the status or details of an attempt.
When the result is available, it is returned in the response.
Call the Get a face authentication endpoint, and provide the authentication ID as the {face_authentication_id} path parameter.
get
https://identity-verification.checkout.com/face-authentications/{face_authentication_id}
The response returns:
- The authentication status
- One or more response codes
- A URL to download an image captured from the face video, if the result is available
If the authentication is later audited and the status updated, you receive an Face authentication audit completed webhook.
If requested by an applicant under the General Data Protection Regulation (GDPR), you can remove the following personally identifiable information (PII) from the face authentication:
- External applicant name – The name you have on record for the applicant.
- Applicant email – The applicant's email address.
Note
Call the Anonymize a face authentication endpoint, and provide the authentication ID as the {face_authentication_id} path parameter.
get
https://identity-verification.checkout.com/face-authentications/{face_authentication_id}/anonymize
You receive a Face authentication anonymized webhook.