Verify identities
Beta

Last updated: September 24, 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.
Create a profile for the applicant whose identity you want to verify.

When you request to enable Identities, your account manager provides you an Identity Verification 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
ID 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 ID 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 an identity verification linked to the applicant's profile.
Create an attempt and redirect the applicant.
Get the identity verification to see the result.
Get the identity verification report.
You can also test your integration.

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

applicant_id – The applicant ID from the id field in the Create an applicant response
declared_data.name – The applicant's name
user_journey_id – Your Identity Verification 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 identity verification, the identity verification status must be one of the following:

created
pending
capture_in_progress
retry_required

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

Provide the following in the request body:

redirect_url field – Provide the URL to redirect the applicant to after they complete the verification.
client_information.pre_selected_residence_country field – Optionally, the applicant's country of residence

Information

Providing the applicant's country of residence 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  "client_information": {
4    "pre_selected_residence_country": "FR"
5  }
6}


1{
2  "id": "iatp_tkoi5db4hryu5cei5vwoabrPoQ",
3  "created_on": "2024-07-21T17:32:28Z",
4  "modified_on": "2024-07-21T17:40:32Z",
5  "client_information": {
6    "pre_selected_residence_country": "FR"
7  },
8  "redirect_url": "https://myweb.site?query-param=hello",
9  "status": "pending_redirection",
10  "response_codes": [ ],
11  "_links": {
12    "verification_url": {
13      "href": "https://idv.checkout.com/4hryu5cei5/"
14    },
15    "self": {
16      "href": "https://identity-verification.sandbox.checkout.com/identity-verifications/idv_01j58p8rw1hvterhqt66xn6js2/attempts/iatp_tkoi5db4hryu5cei5vwoabrPoQ"
17    }
18  }
19}

The response returns:

The attempt ID in the id field, prefixed with iatp_
The attempt URL in the verification_url field, which is valid for 15 minutes
The attempt status pending_redirection

The identity verification status changes to pending and you receive an Identity verification opened webhook.

Redirect the applicant to the attempt URL via web.

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:

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 one of the following: `approved` – The identity verification is successful. `declined` – The identity verification is declined. If you want to enable the applicant to retry, create a new verification. You receive an Identity verification report created webhook.

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 one of the following:

approved – The identity verification is successful.
declined – The identity verification is declined. If you want to enable the applicant to retry, create a new verification.

You receive an Identity verification report created webhook.

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.

Information

You can use the response codes returned in webhooks to implement your own business logic.

We recommend sharing guidance from the response codes with the applicant 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.

You can manage attempts using the following endpoints:

Get identity verification attempts – View all attempts for a verification.
Get an identity verification attempt – View the details of a specific attempt.

You can retrieve the identity 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 Get 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 identity verification status
One or more response codes if the status is approved, declined, inconclusive, pending, 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 ID 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 identity verification is provided in PDF format. When the report is ready, you receive an Identity verification report created webhook.

Call the Get identity verification report endpoint, and provide the identity 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 from an identity verification under the GDPR, you can use the Anonymize an identity verification endpoint.

You receive an Identity verification anonymized webhook.

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

To test your integration, see Identity Verification testing.

Verify identities
Beta

Before you begin

Configuration

How it works

Create a verification

Request example

Response example

Create an attempt

Information

Request example

Response example

Redirect the applicant

Note

Information

Manage attempts

Get a verification

Response example

Get the report

Response example

Remove personal data

Audits

Test your integration