# Authenticate with biometrics using the API 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](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). --- ## Before you start - You must have already integrated the [Identity Verification](https://www.checkout.com/docs/business-operations/manage-identities/verify-identities.md) solution and verified the applicant. - The applicant must already have a [profile](https://www.checkout.com/docs/business-operations/manage-identities/manage-applicants.md) 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](https://www.checkout.com/docs/developer-resources/codes/identities-codes.md). - [Subscribe to Face Authentication webhooks](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Face_Authentication). ### Configuration 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](https://www.checkout.com/docs/business-operations/manage-identities/verify-identities/using-the-api.md#Configuration) 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 --- ## How it works 1. [Retrieve the applicant ID](https://www.checkout.com/docs/business-operations/manage-identities/manage-applicants/using-the-api.md#View_an_applicant_ID). 2. Create an authentication linked to the applicant's profile. 3. Create an attempt. 4. Redirect the applicant to the attempt. 5. View the authentication result. 6. If requested, you can remove the applicant's personal details from the authentication. --- ## Create an authentication Call the [Create a face authentication](https://api-reference.checkout.com/tag/Face-Authentication/#operation/create_face_authentication) endpoint, and provide the following fields: - `applicant_id` – The applicant ID. - `user_journey_id` – The relevant Face Authentication configuration ID. **Production** `POST` `https://identity-verification.checkout.com/face-authentications` **Sandbox** `POST` `https://identity-verification.sandbox.checkout.com/face-authentications` ### Request example ```json { "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we", "user_journey_id": "usj_w41kh4hfdm86589y068qz2w2pg9" } ``` ### Response example ```json { "id": "fav_mtta050yudd54y5iqb5ijh8jtvz", "created_on": "2025-07-21T17:32:28Z", "modified_on": "2025-07-21T17:40:32Z", "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we", "user_journey_id": "usj_w41kh4hfdm86589y068qz2w2pg9", "status": "created", "response_codes": [], "_links": { "self": { "href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz" }, "applicant": { "href": "https://identity-verification.checkout.com/applicants/aplt_lkoi5db4hryu5cei5vwoabqere" } } } ``` 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](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook. --- ## Create an attempt Call the [Create a face authentication attempt](https://api-reference.checkout.com/tag/Face-Authentication/#operation/create_fav_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. **Production** `POST` `https://identity-verification.checkout.com/face-authentications/{face_authentication_id}/attempts` **Sandbox** `POST` `https://identity-verification.sandbox.checkout.com/face-authentications/{face_authentication_id}/attempts` ### Request example ```json { "redirect_url": "https://myweb.site?query-param=hello", "client_information": { "pre_selected_residence_country": "FR", "pre_selected_language": "en-US" } } ``` ### Response example ```json { "id": "fatp_nk1wbmmczqumwt95k3v39mhbh2w", "created_on": "2025-07-21T17:32:28Z", "modified_on": "2025-07-21T17:40:32Z", "client_information": { "pre_selected_residence_country": "FR", "pre_selected_language": "en-US" }, "applicant_session_information": { "ip_address": "123.123.123.01" }, "redirect_url": "https://myweb.site?query-param=hello", "status": "pending_redirection", "response_codes": [], "_links": { "verification_url": { "href": "https://idv.checkout.com/4hryu5cei5/" }, "self": { "href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w" } } } ``` The response returns: - The attempt ID in the `id` field, prefixed with `fatp_` - The attempt URL, which is valid for 15 minutes, in the `verification_url` field The attempt status changes to `pending_redirection` and the authentication status changes to `pending`.
You receive a [Face authentication opened](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook. --- ## Redirect the applicant 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. **Successful attempt** 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 `capture_in_progress`.

You receive a [Face authentication started](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook.

When successfully completed, the attempt status changes to `completed`.

You receive a [Face authentication capture completed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook. | | Checkout.com processes the authentication | The authentication status changes to `checks_in_progress`.

When processing is complete, you receive a [Face authentication checks completed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook.

You may receive the checks completed webhook simultaneously with the capture completed webhook. | | Result is available | The authentication status changes to either `approved` or `declined`.

If the applicant is declined, you can create a new authentication. | **Unsuccessful attempt** An attempt may be unsuccessful due to the following scenarios: | Scenario | Description | | --- | --- | | Attempt URL expires | The attempt status changes to `expired`.

You receive a [Face authentication link expired](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook.

Recommended action – Create a new attempt. | | Applicant refuses the authentication | The authentication status changes to `refused`.

The attempt status changes to `capture_refused`.

You receive a [Face authentication capture refused](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook.

Suggest an alternative authentication method to the applicant. | | Applicant drops out of the attempt | The attempt status changes to `capture_aborted`.

You receive a [Face authentication capture aborted](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook.

Recommended action – You can create a new attempt. | | Applicant needs to retry | The authentication status changes to `retry_required`.

You receive a [Face authentication retry requested](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook.

When you create a new attempt, the status of the previous attempt changes to `terminated`.

You receive a [Face authentication closed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook, followed by an [Face authentication reset](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook.

Recommended action – Redirect the applicant to the new attempt URL. | | Result is inconclusive | The authentication status changes to `inconclusive`.

The attempt status changes to `checks_inconclusive`.

You receive a [Face authentication checks inconclusive](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook.

Recommended action – You can create a new attempt. | > **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. ### View attempts You can retrieve face authentication attempts using the following endpoints: - [Get face authentication attempts](https://api-reference.checkout.com/tag/Face-Authentication/#operation/list_fav_attempts) – Retrieve all attempts for an authentication. - [Get a face authentication attempt](https://api-reference.checkout.com/tag/Face-Authentication/#operation/get_fav_attempt) – Retrieve the details for a specific attempt. --- ## View the authentication 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](https://api-reference.checkout.com/tag/Face-Authentication/#operation/retrieve_face_authentication) endpoint, and provide the authentication ID as the `{face_authentication_id}` path parameter. **Production** `GET` `https://identity-verification.checkout.com/face-authentications/{face_authentication_id}` **Sandbox** `GET` `https://identity-verification.sandbox.checkout.com/face-authentications/{face_authentication_id}` ### Response example ```json { "id": "fav_mtta050yudd54y5iqb5ijh8jtvz", "created_on": "2025-07-21T17:32:28Z", "modified_on": "2025-07-21T17:40:32Z", "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we", "user_journey_id": "usj_w41kh4hfdm86589y068qz2w2pg9", "status": "declined", "response_codes": [ { "code": 62311, "summary": "face_face_mismatch" } ], "face": { "image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/live_face/bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921946714.png?response-content-type=image%2Fpng&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20231006T174223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4" }, "_links": { "self": { "href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz" }, "applicant": { "href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou" } } } ``` 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 ### Audits If the authentication is later audited and the status updated, you receive an [Face authentication audit completed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook. --- ## Remove personal details 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** > > Removing an applicant's PII is permanent. You cannot undo this action. > Any information from the applicant's checks that is not linked to their personal identity is retained for your records. Call the [Anonymize a face authentication](https://api-reference.checkout.com/tag/Face-Authentication/#operation/anonymize_face_authentication) endpoint, and provide the authentication ID as the `{face_authentication_id}` path parameter. **Production** `GET` `https://identity-verification.checkout.com/face-authentications/{face_authentication_id}/anonymize` **Sandbox** `GET` `https://identity-verification.sandbox.checkout.com/face-authentications/{face_authentication_id}/anonymize` ### Response example ```json { "id": "fav_mtta050yudd54y5iqb5ijh8jtvz", "created_on": "2025-07-21T17:32:28Z", "modified_on": "2025-07-21T17:40:32Z", "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we", "user_journey_id": "usj_t5bdzsdmi57ehhkrnmp5omjimu", "status": "approved", "response_codes": [ { "code": 10000, "summary": "approved" } ], "risk_labels": [ "multiple_faces_detected" ], "_links": { "self": { "href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz" }, "applicant": { "href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou" } } } ``` You receive a [Face authentication anonymized](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/face-authentication-webhooks.md) webhook.