Verify ID Documents
Beta

Last updated: September 24, 2025

The ID Document Verification solution enables you to verify that a person's ID document is authentic, using photos or scans of the document.

Information

To enable ID Document Verification, contact your account manager or request support.

Prepare to handle statuses, attempts, and response codes.
Set up your webhook receiver and prepare to handle webhooks.
The person whose document you want to verify must already have an applicant profile.

When you request to enable ID Document Verification, your account manager provides you an ID Document Verification configuration ID, prefixed with usj_. This is different to your Identity Verification and Face Authentication configuration IDs.

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 verification result from Checkout.com
The ID documents you want to accept, if supported by Checkout.com
The data you want to extract from documents

The applicant provides images of their ID document, which you upload to Checkout.com. Checkout.com checks if:

The image quality is sufficient to process.
The images and the document are authentic.
The name the applicant provided matches the document.
The image files contain malware.

We share the result and a report.

Follow these steps:

Create an ID document verification linked to the applicant's profile.
Create an attempt and upload the document images.
Get the ID document verification to see the detailed result.
Get the ID document verification report.

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

applicant_id – The applicant ID from the id field in the Create an applicant response
user_journey_id – Your ID Document Verification configuration ID
declared_data.name – The name the applicant provided to compare to the name extracted from the document

post

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


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


1{
2  "id": "iddv_tkoi5db4hryu5cei5vwoabr7we",
3  "created_on": "2025-07-21T17:32:28Z",
4  "modified_on": "2025-07-21T17:40:32Z",
5  "user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
6  "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
7  "status": "approved",
8  "response_codes": [
9    {
10      "code": 10000,
11      "summary": "approved"
12    }
13  ],
14  "declared_data": {
15    "name": "Hannah Bret"
16  },
17  "document": {
18    "full_name": "Hannah Bret",
19    "birth_date": "1994-10-15",
20    "document_type": "ID",
21    "document_issuing_country": "US",
22    "front_image_signed_url": "https://storage-b.env/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"
23  },
24  "_links": {
25    "self": {
26      "href": "https://identity-verification.checkout.com/id-document-verifications/iddv_tkoi5db4hryu5cei5vwoabr7we"
27    },
28    "applicant": {
29      "href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we"
30    }
31  }
32}

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

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

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

Provide the following in the request body:

document_front – The image of the front of the document
document_back – Optionally, the image of the back of the document, if relevant

Images must not exceed 10MB in size and must be in one of the following formats:

JPEG
PDF
PNG

post

https://identity-verification.sandbox.checkout.com/id-document-verifications/{id_document_verification_id}/attempts


1{
2  "document_front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD…\n"
3}


1{
2  "id": "datp_tkoi5db4hryu5cei5vwoabr7we",
3  "created_on": "2025-07-21T17:32:28Z",
4  "modified_on": "2025-07-21T17:40:32Z",
5  "status": "completed",
6  "response_codes": [],
7  "_links": {
8    "self": {
9      "href": "https://api.sandbox.checkout.com/id-document-verifications/datp_tkoi5db4hryu5cei5vwoabr7we"
10    }
11  }
12}

The response returns the attempt ID in the id field, prefixed with datp_.

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
Checkout.com checks image quality	The ID document verification status and attempt status change to `quality_checks_in_progress`.
Checkout.com checks for authenticity	The ID document verification status and attempt status change to `checks_in_progress`. You receive an ID document verification started webhook.
Verification is complete	The attempt status changes to `completed`. The ID document verification status changes to one of the following: `approved` – The document is verified successfully. `declined` – The document is declined. If you want to enable the applicant to retry, create a new ID document verification. You receive an ID document verification checks completed webhook.

Checkout.com checks image quality

The ID document verification status and attempt status change to quality_checks_in_progress.

Checkout.com checks for authenticity

The ID document verification status and attempt status change to checks_in_progress.

You receive an ID document verification started webhook.

Verification is complete

The attempt status changes to completed.

The ID document verification status changes to one of the following:

approved – The document is verified successfully.
declined – The document is declined. If you want to enable the applicant to retry, create a new ID document verification.

You receive an ID document verification checks completed webhook.

An attempt may be unsuccessful due to the following scenarios:

Scenario Description

Scenario	Description
Checks inconclusive	The ID document verification status changes to `retry_required`. The attempt status changes to `checks_inconclusive`. You receive an ID document verification checks inconclusive webhook. You need to create a new attempt with different images of the document.
Image quality insufficient	The ID document verification status changes to `retry_required`. The attempt status changes to `quality_checks_aborted`. You need to create a new attempt with different images of the document.
Attempt forcibly closed when new attempt created	The attempt status changes to `terminated`. You receive an ID document verification closed webhook. You need to create a new attempt with different images of the document.

Checks inconclusive

The ID document verification status changes to retry_required.

The attempt status changes to checks_inconclusive.

You receive an ID document verification checks inconclusive webhook.

You need to create a new attempt with different images of the document.

Image quality insufficient

The ID document verification status changes to retry_required.

The attempt status changes to quality_checks_aborted.

You need to create a new attempt with different images of the document.

Attempt forcibly closed when new attempt created

The attempt status changes to terminated.

You receive an ID document verification closed webhook.

You need to create a new attempt with different images of the document.

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 ID document verification attempts – Retrieve all attempts for a verification.
Get an ID document verification attempt – Retrieve the details about a specific attempt.

You can get the details of the ID document 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 ID document verification endpoint, and provide the ID document verification ID as the {id_document_verification_id} path parameter.

get

https://identity-verification.sandbox.checkout.com/id_document_verifications/{id_document_verification_id}


1{
2  "id": "iddv_tkoi5db4hryu5cei5vwoabr7we",
3  "created_on": "2025-07-21T17:32:28Z",
4  "modified_on": "2025-07-21T17:40:32Z",
5  "user_journey_id": "usj_tkoi5db4hryu5cei5vwoabr7we",
6  "applicant_id": "aplt_tkoi5db4hryu5cei5vwoabr7we",
7  "status": "approved",
8  "response_codes": [
9    {
10      "code": 10000,
11      "summary": "approved"
12    }
13  ],
14  "declared_data": {
15    "name": "Hannah Bret"
16  },
17  "document": {
18    "full_name": "Hannah Bret",
19    "birth_date": "1994-10-15",
20    "document_type": "ID",
21    "document_issuing_country": "US",
22    "front_image_signed_url": "https://storage-b.env/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"
23  },
24  "_links": {
25    "self": {
26      "href": "https://identity-verification.checkout.com/id-document-verifications/iddv_tkoi5db4hryu5cei5vwoabr7we"
27    },
28    "applicant": {
29      "href": "https://identity-verification.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we"
30    }
31  }
32}

The response returns:

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

If the result is available, it also returns the document data and the best image of the document, in the documents object.

When the ID document verification status is approved or declined and the report is available, you receive an ID document verification report created webhook.

Call the Get ID document verification report endpoint, and provide the ID document verification ID as the {id_document_verification_id} path parameter.

get

https://identity-verification.sandbox.checkout.com/id-document-verifications/{id_document_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 their ID document verification under the GDPR, you can use the Anonymize an ID document verification endpoint.

You receive an ID document verification anonymized webhook.

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

Verify ID Documents
Beta

Information

Before you begin

Configuration

How it works

Create a verification

Request example

Response example

Create an attempt

Image format

Request example

Response example

Note

Information

Manage attempts

Get the verification

Response example

Get the report

Response example

Remove personal data

Audits