# Live verification

Live verification consists of verifying the user’s identity remotely through a live video. This feature contributes to mitigating fraud risk while optimizing the user experience.

Gear icon

Configuration – Environment configuration by Treezor

Contact Treezor to use one of the live verification features.

Treezor relies on a live verification provider which offers two ways to verify user identity. You can use only one of these two methods.

Method Description
Liveness Requires a video of the end user, their identity proof, and a SEPA transfer into their Treezor Wallet as an extra validation step.
Certified video (PVID) Requires a video of the end users and their identity proof. It contains challenges for the user to complete, so no extra validation step is necessary. PVID is ANSSI-certified.

Both features use the same endpoint with a transparent behavior.

Bulb icon

Tip – The KYC live verification interface is customizable

Contact Treezor to change the colors, logo, redirection URL once the process ends, etc. More information available in the KYC Liveness implementation guide (opens new window) in Treezor's Support Center.

# Process

Documents upload live verification
  1. You initiate a live verification for the User – /v1/users/{userId}/Kycliveness.
  2. Treezor answers with the live verification URL (identification-url).
  3. You redirect the User to the identification-url.
  4. The User follows the step-by-step live verification process, hence uploading the document.
  5. Treezor keeps you informed of the documents processing with the KYC Liveness webhooks.
  6. Once the kycliveness.update webhook returns a kyc-status set to processed, you may request a KYC review:
    a. Retrieve the documents/v1/users/{userId}/Kycliveness
    b. Request a KYC review/v1/users/{userId}/Kycreview
  7. Treezor sends you the user.kycreview webhook upon validation or refusal.

Note that the live verification process may take some time.

Please don't call the /v1/users/{userId}/Kycliveness endpoint for a given user before the previous live verification is completed. When this situation occurs:

  • The newer request replaces the previous one.
  • Trying to upload documents for the first live verification results in an HTTP error.

# Key attributes (webhooks)

Live verification relies exclusively on webhooks to provide you with information regarding the process:

  • kycliveness.create – Received when the end user completes (or abandons) the live verification process.
  • kycliveness.update – Received when Treezor's identity verification partner completes the verification.

Below are some of the key attributes you may find in these webhooks.

Attribute Type Description
kyc-status string The status of the live verification process. See the redirectURL query parameters.
comment string Comment from Treezor providing additional information regarding the live verification process.
reasons array List of reason codes and messages indicating why the user has been refused.
See the list of reason codes below.

# Reason codes (reason-code)

When using the live verification feature (either Liveness or Certified video), the kycliveness.update webhook returns the reason-code and the corresponding reason-message, providing insights on the refusal.

Some of these errors are sensitive regarding AML/CFT, please remember not to share the reasons for refusal with your end users when that’s the case.

Code Message
1201 Applicant did not have a sufficient connexion
1301 Applicant’s document video is too blurry (mostly due to too much movement but if this error persists the camera quality might be at fault)
1302 Applicant has not presented the front of the document
1303 Applicant has not presented the back of the document
1304 Applicant hides part of the document
1305 Applicant did not present a dynamic view of the document
1310 Applicant’s video of their face is too blurry (mostly due to too much movement but if this error persists the camera quality might be at fault)
1311 Applicant has not presented a face
1312 Applicant did not show the full front view of their face
1313 Applicant did not move to prove the liveness
1320 Applicant performed their id verification under poor lighting conditions
1901 Internal non-categorizable error
1911 The received videos cannot be played
2101 Applicant presented an expired document
2102 Applicant presented a document which is not accepted
2103 Applicant has submitted a damaged document
2201 Applicant presented a photocopy of the document
2202 Applicant presented the document on a screen
2301 Applicant has submitted a counterfeit or falsification
2302 Applicant presented a document declared as stolen or lost
2303 Applicant presented the front and back of two different documents
2304 Applicant is not the rightful owner of the document
2305 Applicant presented another person's face
2306 Applicant has altered his/her appearance
2307 Applicant has digitally altered the videos
2399 Generic code when a fraud has been detected within a certified identity verification
2401 Applicant’s identity does not match with the expected one
2402 Applicant used a device that has been technically altered
2403 Applicant seems to have performed the check against his will

# Initiate a live verification

Before initiating the live verification process, the User must be created with the relevant attributes (as required by Treezor Compliance).

At least the firstname, lastname, and birthday of the user must be populated, otherwise, the API call returns an HTTP 428 error.

# Parameters

You can optionally override the default URL to which the user will be redirected after the live verification.

Attribute Type Description
redirectUrl string The URL to which the User will be redirected after the live verification.

Additional information is added to the defined redirect URL in the form of query parameters. This can help the end user understand why a live verification process has been aborted.

The query parameters provided with the redirectUrl are the following:

Parameter Description
identification_id The unique identifier of the live verification process.
status The status of the live verification, which in this case can be either processing in case of success or aborted for failures.
return_reason The reason for the live verification process abortion.
error_type Indicates the type of error that led to the live verification process abortion.
More about the Redirect URL query parameters

If you take the following URL:

redirect_url?identification_id=123&status=aborted&return_reason=error&error_type=device_not_found

You can deduce that the identification process 123 was aborted due to an error; the device was not found (i.e., the device did not have any camera).

Here is the list of values for the query parameters:

status return_reason error_type description
processing none none The user completed their verification.
aborted refusal none The user refused to perform the verification now.
aborted no_document none The user did not have their document available to them.
aborted verify_later none The user refused to start the verification process.
aborted focus-lost none The user switched tabs/application while performing the id verification.
aborted connections_issue bad_connexion The connection was not good enough.
aborted doc_instructions_not_followed challenge_timeout The user did not follow the instruction for the document challenge.
aborted face_instructions_not_followed challenge_timeout The user did not follow the instruction for the face challenge.
aborted error bad_connexion The connection was not good enough.
aborted error no_SMS The user did not receive the SMS.
aborted error publish Error during video connection.
aborted error device_not_allowed The user refused to give access to their camera.
aborted error browser-not-supported The browser was not supported.
aborted error device_not_found The user’s device did not have any camera.
aborted error wrong_phone_number The user wanted to change their phone number and were not allowed to for security reasons.

# Request

You can use the following request to initiate the live verification process.

Answers with a 201 HTTP Status Code and returns the identifier of the verification process and the identification-url. The latter is where the end user is to be redirected to go through the live verification process.

Once redirected, end users are guided through the steps for the relevant live verification feature.

Info icon

Information – The redirection link may not be supported by the end user's device

See the redirectURL query parameters to know which error is returned when this occurs.

# End user live verification

Once redirected, end users are guided through the live verification steps:

  • Which differ depending on the live verification type.
  • Which documents vary depending on the country of the end user.
Click to see the KYC Liveness steps for your end users (mobile) Liveness user steps 1 Liveness user steps 2 Liveness user steps 3 Liveness user steps 4
Click to see the Certified video steps for your end users (mobile) Certified video user steps 1 Certified video user steps 2 Certified video user steps 3

After the last step:

  • The user is redirected to the redirectUrl or the URL configured with Treezor.
  • Treezor sends you a kycliveness.create webhook with a kyc-status set to processing.

# Retrieve the live verification document

Once you have received the kycliveness.update webhook with a kyc-status set to processed, you must retrieve the documents from the live verification provider for them to be uploaded to Treezor.

These documents include documents uploaded by the end user during the process and the live verification process synthesis document, which is either:

  • Liveness result for the liveness process (documentTypeId = 26).
  • Certified Liveness Result for the certified video process (documentTypeId = 34).

To retrieve the documents, use the following request.

Answers with an HTTP 200 status code and makes the documents available for download.

Treezor sends you as many document.create webhooks as there are documents for the user’s live verification. You can make your KYC Review request only once you've received all the document creation webhooks.

# Download the live verification documents

If you're eligible, you may be able to collect some of the uploaded documents whose documentTypeId allows for it.

Gear icon

Configuration – Download is not enabled by default

Please contact Treezor to request access to this feature.

Downloading a document is a 2-step process, in which you:

  1. Request the download URL
  2. Download the document within 30 seconds

# Request the download URL

To request the presigned download URL, you need the corresponding documentId (available in the document.create webhook for instance).

Returns the URL to download the document, with all the necessary query parameters for the next step.

# Download the document

You have 30 seconds to download the document from the moment the presigned URL has been generated in the previous step.

The document is returned in its initial format.

# Request a KYC Review for the User

Before requesting a KYC review from Treezor, please make sure all the information and documents are properly updated for the user.

You can use the dedicated endpoint:

Warning icon

Alert – Documents must be uploaded for children users too

When there are parent-children hierarchical relationship, in most cases, the KYC Review must only be requested for the parent user. But you may need to upload Documents for the children before that. Please abide by the Treezor Compliance team recommendation for a smooth experience.

Learn more in the KYC Request article.

# Endpoints

Endpoint Description Scope
/v1/users/{userId}/Kycreview Initiate the user KYC review process read_write
/v1/users/{userId}/Kycliveness Initiate the user Live verification process read_write
/v1/users/{userId}/Kycliveness Upload the documents once the Live verification is completed. read_write
/v1/documents/{documentId}/download Retrieve a document download URL read_only
Updated on: 5/20/2024, 12:47:40 PM