Identity Verification
Beta
Last updated: January 15, 2025
The Identity Verification solution enables you to verify the identity of new users who want to onboard with you. This helps you meet compliance requirements and reduce the risk of fraud.
- You redirect the user to a web flow on their mobile device.
- The user captures video of their face and ID document.
- Checkout.com checks if the document is genuine and matches the person in the video.
- We share the result and a full report.
Information
To enable Identity Verification and request a user journey ID, contact your Account Manager or [email protected].
- You need a Checkout.com test account, with Identity Verification enabled.
- Set up an authentication mechanism for your API requests, using OAuth 2.0 or API keys.
- Prepare to handle the verification statuses, and configure appropriate user paths for each status.
- Set up your webhook receiver and prepare to handle notifications about flow events and the result.
- Set up web flow redirection and user return.
- Optionally, customize the user interface of the web flow.
When you request to enable Identity Verification, your Account Manager provides you a user journey ID. For example, usj_tkoi5db4hryu5cei5vwoabr7we
.
Provide this ID whenever you create a verification.
The ID can configure the following elements of the flow:
- Primarily automated processing or a systematic manual review of each verification
- The ID documents you want to accept, if supported by Checkout.com
- The data you want to extract from documents
- The guaranteed response time from Checkout.com
- Create an applicant ID for the user.
- Create a verification.
- Create an attempt.
- Redirect the user.
- Retrieve the verification for details about the result or the user's session.
- Retrieve the report for the verification.

Call the Create an applicant endpoint. Optionally, provide the following fields:
external_applicant_id
– Your identifier for the useremail
– The user's email address
post
https://identity-verification.sandbox.checkout.com/applicants
1{2"external_applicant_id": "ext_osdfdfdb4hryu5cei5vwoabrk5k",3"email": "[email protected]"4}
The response returns an applicant id
, which you need for the Create a verification step.
1{2"id": "aplt_tkoi5db4hryu5cei5vwoabr7we",3"created_on": "2024-07-21T17:32:28Z",4"modified_on": "2024-07-21T17:40:32Z",5"external_applicant_id": "ext_osdfdfdb4hryu5cei5vwoabrk5k",6"email": "[email protected]",7"_links": {8"self": {9"href": "https://identity-verification.sandbox.checkout.com/applicants/aplt_tkoi5db4hryu5cei5vwoabr7we"10}11}12}
You can also manage your user profiles using the following endpoints:
- Retrieve an applicant – View the details of the user's profile.
- Update an applicant – Update your reference for the user or their email address.
- Anonymize an applicant – Delete a user's personal data under the GDPR, if requested.
Call the Create an identity verification endpoint, and provide the following fields:
applicant_id
– The applicantid
from the Create an applicant responsedeclared_data.name
– The user's nameuser_journey_id
– The user journey configuration
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}
The response returns the identity verification id
, which you need for the Create an attempt step.
The verification status changes to created
.
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}
Call the Create an attempt endpoint, and provide the following:
identity_verification_id
path – The verificationid
from the Create an identity verification responseredirect_url
field – Your return page URL to redirect the user after completing the flow- Optionally:
phone_number
object – The user's mobile phone number for receiving theverification_url
via SMSclient_information.pre_selected_residence_country
field – The user's residence country
This shortens the web flow and improves the experience because the user does not have to select the 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}
The response returns:
- The attempt
id
and theverification_url
to redirect the user to - The attempt status and response code
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}
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 default expiration time for the URL is 15 minutes.
Checkout.com informs you about the progress of the flow using the verification status shared in the webhook notifications. You can also retrieve a verification to check its status at any time.
If the first attempt is unsuccessful and the verification 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 help them succeed in their next attempt. 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 – View all attempts for an identity verification.
- Retrieve an attempt – View the details of a specific attempt.
You can retrieve an identity verification at any time – for example, to check the status or details about the user's session. To view the result, the verification status must be approved
or declined
.
Call the Retrieve an identity verification endpoint, and provide the following:
identity_verification_id
path – The verification id
from the Create an identity verification response
get
https://identity-verification.sandbox.checkout.com/identity-verifications/{identity_verification_id}
The response returns:
- The verification status
- One or more response codes if the
status
isapproved
,declined
,refused
,retry_required
If the result is available, it also returns:
- Information about the user's identity in the
verified_identity
object - The user's ID document data and the best image of the document, in the
documents
object - The best image of the user's face in the
face
object
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}
If a user requests you to delete their personal data under the GDPR, you can use the Anonymize an identity verification endpoint.
When you receive the identity_verification_report_created
webhook, the detailed report of the identity verification is available in PDF format.
Call the Retrieve identity verification report endpoint, and provide the following:
identity_verification_id
path – The verification id
from the Create an identity verification response
get
https://identity-verification.sandbox.checkout.com/identity-verifications/{identity_verification_id}/pdf-report
The response returns a URL where you can download the report.
1{2"value": {3"pdf_report": "https://www.example.com/pdf"4}5}