Face Authentication
Beta

Last updated: January 15, 2025

The Face Authentication solution enables you to confirm a user is the same person whose identity you've successfully verified using the Identity Verification solution. This helps you decide whether to allow them to access your services.

The solution works as follows:

You redirect the user to a web flow on their mobile device.
The user captures a video of their face.
Checkout.com compares the video to one from a previous successful identity verification or face authentication, to check if they show the same person.
We send you the result.

Information

To enable Face Authentication and request a user journey ID, contact your Account Manager or [email protected].

You must have already integrated the Identity Verification solution and verified the user.
The user must already have an applicant ID.
You must have a non-anonymized face video from a previous successful identity verification or face authentication available for the user.
Prepare to handle the authentication statuses.
Set up a webhook receiver to handle the Face Authentication webhooks.

Information

You can configure how long to retain Identity Verification face videos to ensure you have one available for Face Authentication.

When you request to enable Face Authentication, your Account Manager provides you a user journey ID. For example, usj_w41kh4hfdm86589y068qz2w2pg9. Provide this ID whenever you create an authentication.

Create a face authentication for the user.
Create an attempt.
Redirect the user to the web flow.
Retrieve the authentication for details about the result or the user's session.

Call the Create a face authentication endpoint, and provide the following fields:

applicant_id – The user's applicant ID from a previous identity verification or face authentication
user_journey_id – Your user journey ID for Face Authentication

post

https://identity-verification.sandbox.checkout.com/face-authentications


1{
2  "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
3  "user_journey_id": "usj_w41kh4hfdm86589y068qz2w2pg9"
4}

The response returns a face authentication ID in the id field, prefixed with fav, which you need for the Create an attempt step.


1{
2  "id": "fav_mtta050yudd54y5iqb5ijh8jtvz",
3  "created_on": "2024-07-21T17:32:28Z",
4  "modified_on": "2024-07-21T17:40:32Z",
5  "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
6  "user_journey_id": "usj_w41kh4hfdm86589y068qz2w2pg9",
7  "status": "created",
8  "response_codes": [],
9  "_links": {
10    "self": {
11      "href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz"
12    },
13    "applicant": {
14      "href": "https://identity-verification.checkout.com/applicants/aplt_lkoi5db4hryu5cei5vwoabqere"
15    }
16  }
17}

To create a session for the user to attempt the web flow, the authentication status must be one of the following:

created
pending
capture_in_progress
retry_required

Call the Create an attempt endpoint, and provide the authentication id from the Create a face authentication response as the {face_authentication_id} path parameter.

In the request payload:

redirect_url field – Provide the URL to redirect the user to after they complete the flow.
phone_number object – Optionally, provide the user's mobile phone number to send the verification_url to via SMS.
client_information.pre_selected_residence_country field – Optionally, provide the user's residence country.
Specifying the country simplifies the web flow because the user does not have to manually select it manually.

post

https://identity-verification.sandbox.checkout.com/face-authentications/{face_authentication_id}/attempts


1{
2  "redirect_url": "https://myweb.site?query-param=hello",
3  "phone_number": {
4    "country_code": "+1",
5    "number": "2068133616"
6  },
7  "client_information": {
8    "pre_selected_residence_country": "FR"
9  }
10}

The response returns the attempt id prefixed with fatp, and the verification_url to redirect the user to.


1{
2  "id": "fatp_nk1wbmmczqumwt95k3v39mhbh2w",
3  "created_on": "2024-07-21T17:32:28Z",
4  "modified_on": "2024-07-21T17:40:32Z",
5  "phone_number": {
6    "country_code": "+1",
7    "number": "2068133616"
8  },
9  "client_information": {
10    "pre_selected_residence_country": "FR"
11  },
12  "applicant_session_information": {
13    "ip_address": "123.123.123.01"
14  },
15  "redirect_url": "https://myweb.site?query-param=hello",
16  "status": "pending_redirection",
17  "response_codes": [],
18  "_links": {
19    "verification_url": {
20      "href": "https://idv.checkout.com/4hryu5cei5/"
21    },
22    "self": {
23      "href": "https://identity-verification.sandbox.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz/attempts/fatp_nk1wbmmczqumwt95k3v39mhbh2w"
24    }
25  }
26}

Redirect the user to the verification_url you received in the Create an attempt response. To test the web flow, open the URL in your browser and follow the instructions.

Information

The URL's default expiration time is 15 minutes.

Checkout.com informs you about the progress of the flow using the authentication status shared in the Face Authentication webhooks. You can also retrieve the authentication to check its status any time.

If the first attempt is unsuccessful and the authentication status changes to retry_required, you can create a new attempt for the user to retry the flow.

We recommend sharing guidance from the response code with the user to ensure their next attempt succeeds. For example, if the user's data connection is poor, let them know so they can try to improve it.

You can also manage attempts using the following endpoints:

List attempts – Retrieve all attempts for a face authentication.
Retrieve an attempt – Retrieve the details of a specific attempt.

You can retrieve a face authentication at any time – for example, to check the status or details about the user's session. To view the result, the authentication status must be approved or declined.

Call the Retrieve a face authentication endpoint, and provide the id from the Create a face authentication response 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


1{
2    "id": "fav_mtta050yudd54y5iqb5ijh8jtvz",
3    "created_on": "2024-07-21T17:32:28Z",
4    "modified_on": "2024-07-21T17:40:32Z",
5    "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
6    "user_journey_id": "usj_w41kh4hfdm86589y068qz2w2pg9",
7    "status": "declined",
8    "response_codes": [
9      {
10        "code": 62311,
11        "summary": "face_face_mismatch"
12      }
13    ],
14    "face": {
15      "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"
16    },
17    "_links": {
18      "self": {
19        "href": "https://identity-verification.checkout.com/face-authentications/fav_mtta050yudd54y5iqb5ijh8jtvz"
20      },
21      "applicant": {
22        "href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7ou"
23      }
24    }
25  }

If the user requests that you delete their personal data under the GDPR, you can use the Anonymize a face authentication endpoint.

Face Authentication
Beta

Information

Before you begin

Information

User journey ID

How it works

Create a face authentication

Request example

Response example

Create an attempt

Request example

Response example

Redirect the user

Information

Manage retries

Retrieve the authentication

Response example