Verify identities
Beta

Last updated: June 4, 2025

The Identity Verification solution enables you to verify the identity of a physical person applying to use your services. This helps you meet compliance requirements and reduce the risk of fraud.

You need a Checkout.com test account, with Identities enabled.
Set up an authentication mechanism for your API requests, using OAuth 2.0 or API keys.
Prepare to handle statuses, attempts, and response codes.
Set up your webhook receiver and prepare to handle webhooks.
Set up attempt redirection using web integration.
Create a profile for the applicant whose identity you want to verify.

When you request to enable Identities, your account manager provides you a configuration ID, prefixed with usj_.

You must provide this ID every time you create a verification. It configures the following elements of the solution:

The service level agreement for receiving the result from Checkout.com
Identity documents:
- The documents you want to accept, if supported by Checkout.com
- Whether you require one document or two – primary and secondary
- The data you want to extract from documents
Whether you require a video of the applicant's face
Processing type:
- Fast – Highly automated processing, with human review if required
- Expert – Systematic human review

The applicant captures video of their identity document and face. Checkout.com checks if the document is genuine and matches the person in the video, and shares the result and a full report.

Follow these steps:

Create a verification linked to the applicant's profile.
Create an attempt and redirect the applicant.
Retrieve the verification to see the result.
Retrieve the verification report.

Call the Create an identity verification endpoint, and provide the following fields:

applicant_id – The applicant ID from the Create an applicant response
declared_data.name – The applicant's name
user_journey_id – Your configuration ID

post

https://identity-verification.sandbox.checkout.com/identity-verifications


1{
2  "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
3  "declared_data": {
4    "name": "Hannah Bret"
5  },
6  "user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we"
7}


1{
2  "id": "idv_tkoi5db4hryu5cei5vwoabr7we",
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_tkoi5db4hryu5cei5vwoabr7we",
7  "status": "created",
8  "response_codes": [],
9  "declared_data": {
10    "name": "Hannah Bret",
11    "birth_date": "1994-10-15"
12  },
13  "documents": [],
14  "_links": {
15    "self": {
16      "href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we"
17    },
18    "applicant": {
19      "href": "https://identity-verification.checkout.com/applicants/aplt_lkoi5db4hryu5cei5vwoabqere"
20    }
21  }
22}

The response returns the verification ID in the id field, prefixed with idv_. You need this to create an attempt.

The verification status changes to created and you receive an Identity verification created webhook.

To create a web session for the applicant to attempt the verification, the verification status must be one of the following:

created
pending
capture_in_progress
retry_required

Call the Create an attempt endpoint, and provide the verification ID from the Create a verification response as the {identity_verification_id} path parameter.

Provide the following fields in the request body:

redirect_url – Provide the URL to redirect the applicant to after they complete the verification.
phone_number – If you want to send the applicant the attempt URL via SMS, provide their phone number.
client_information.pre_selected_residence_country field – 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/identity-verifications/{identity_verification_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}


1{
2  "id": "iatp_tkoi5db4hryu5cei5vwoabrPoQ",
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  "redirect_url": "https://myweb.site?query-param=hello",
13  "status": "pending_redirection",
14  "response_codes": [ ],
15  "_links": {
16    "verification_url": {
17      "href": "https://idv.checkout.com/4hryu5cei5/"
18    },
19    "self": {
20      "href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_01j58p8rw1hvterhqt66xn6js2/attempts/iatp_tkoi5db4hryu5cei5vwoabrPoQ"
21    }
22  }
23}

The response returns:

The attempt ID in the id field, prefixed with iatp_
The attempt URL in the verification_url field
The attempt status pending_redirection

The verification status changes to pending and you receive an Identity verification 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:

Scenario Description

Scenario	Description
Applicant starts the attempt	The verification and attempt statuses change to `capture_in_progress`. You receive an Identity verification started webhook. When successfully completed, the attempt status changes to `completed`. You receive an Identity verification capture completed webhook.
Checkout.com processes the verification	The verification status changes to `checks_in_progress`. You can ask the applicant to perform additional checks or to wait for the result. When processing is complete, you receive an Identity verification checks completed webhook. You may receive the checks completed webhook simultaneously with the capture completed webhook.
Result is available	The verification status changes to either `approved` or `declined`. You receive an Identity verification report created webhook. If the applicant is declined, you can create a new verification.

Applicant starts the attempt

The verification and attempt statuses change to capture_in_progress.

You receive an Identity verification started webhook.

When successfully completed, the attempt status changes to completed.

You receive an Identity verification capture completed webhook.

Checkout.com processes the verification

The verification status changes to checks_in_progress.

You can ask the applicant to perform additional checks or to wait for the result.

When processing is complete, you receive an Identity verification checks completed webhook.

You may receive the checks completed webhook simultaneously with the capture completed webhook.

Result is available

The verification status changes to either approved or declined.

You receive an Identity verification report created webhook.

If the applicant is declined, you can create a new verification.

An attempt may be unsuccessful due to the following scenarios:

Scenario	Description
Attempt URL expires	The attempt status changes to `expired`. You receive an Identity verification link expired webhook. You need to create a new attempt.
Applicant refuses the verification	The verification status changes to `refused`. The attempt status changes to `capture_refused`. You receive an Identity verification capture refused webhook. Suggest an alternative verification method to the applicant.
Applicant drops out of the attempt	The attempt status changes to `capture_aborted`. You receive an Identity verification capture aborted webhook. You can create a new attempt.
Applicant needs to retry	The verification status changes to `retry_required`. You receive an Identity verification retry requested webhook. When you create a new attempt, the status of the previous attempt changes to `terminated`. You receive an Identity verification closed webhook, followed by an Identity verification reset webhook. Redirect the applicant to the new attempt URL.
Result is inconclusive	The verification status changes to `inconclusive`. The attempt status changes to `checks_inconclusive`. You receive an Identity verification checks inconclusive webhook. You can create a new attempt.

You can manage attempts using the following endpoints:

List attempts – View all attempts for a verification.
Retrieve an attempt – View the details of a specific attempt.

You can retrieve the verification 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 Retrieve an identity verification endpoint, and provide the verification ID as the {identity_verification_id} path parameter.

get

https://identity-verification.sandbox.checkout.com/identity-verifications/{identity_verification_id}


1{
2  "id": "idv_tkoi5db4hryu5cei5vwoabr7we",
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_5hxpdwegjcbujpth3wdo55d3vm",
7  "status": "approved",
8  "response_codes": [
9    {
10      "code": 10000,
11      "summary": "approved"
12    }
13  ],
14  "verified_identity": {
15    "full_name": "Hannah Bret",
16    "birth_date": "1994-10-15"
17  },
18  "declared_data": {
19    "name": "Hannah Bret",
20    "birth_date": "1994-10-15"
21  },
22  "documents": [
23    {
24      "full_name": "Hannah Bret",
25      "birth_date": "1994-10-15",
26      "document_type": "ID",
27      "document_issuing_country": "US",
28      "front_image_signed_url": "https://storage-b.env.ubble.ai/ubble-ai/NDYOOVHGZPAQ/a54b3393-f02a-47c9-a9c5-2f6ee73560e1/bb603e2f-5de9-40f2-9631-8285a33c24c0/tight_crops/FRA-I5-Front-bb603e2f-5de9-40f2-9631-8285a33c24c0-1679921906596.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=V9jgOdpOdeVSFTkA4ZsG%2F20230327%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230327T163228Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=87d8467ab92cbad7c00171af28e613d495f3ff441ce0ea59dd013d68abc50555"
29    }
30  ],
31  "face": {
32    "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=20230327T163223Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b7d87fec4f11f0df949da7beade2519cf1a51ce70fe9cc1cf0470d73f5340e4"
33  },
34  "phone_number": {
35    "country_code": "+1",
36    "number": "2068133616"
37  },
38  "redirect_url": "https://example.com?query-param=hello",
39  "_links": {
40    "self": {
41      "href": "https://identity-verification.checkout.com/identity-verifications/idv_tkoi5db4hryu5cei5vwoabr7we"
42    },
43    "verification_url": {
44      "href": "https://idv.checkout.com/4hryu5cei5/"
45    }
46  }
47}

The response returns:

The verification status
One or more response codes if the status is approved, declined, refused, retry_required

If the result is available, it also returns:

Information about the applicant's identity in the verified_identity object
The applicant's identity document data and the best image of the document, in the documents object
The best image of the applicant's face in the face object

A detailed report for the verification is provided in PDF format. When the report is ready, you receive an Identity verification report created webhook.

Call the Retrieve an identity verification endpoint, and provide the verification ID as the {identity_verification_id} path parameter.

get

https://identity-verification.sandbox.checkout.com/identity-verifications/{identity_verification_id}/pdf-report


1{
2  "value": {
3    "pdf_report": "https://www.example.com/pdf"
4  }
5}

The response returns a URL where you can download the report.

If an applicant requests that you remove their personal data under the GDPR, you can use the Anonymize an identity verification endpoint.

You receive an Identity verification anonymized webhook.

If the verification is later audited and the status updated, you receive an Identity verification audit completed webhook.

Verify identities
Beta

Before you begin

Configuration

How it works

Create a verification

Request example

Response example

Create an attempt

Request example

Response example

Redirect the applicant

Note

Manage attempts

Retrieve a verification

Response example

Retrieve the report

Response example

Remove personal data

Audits