# 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.
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.
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
- You initiate a live verification for the User –
/v1/users/{userId}/Kycliveness. - Treezor answers with the live verification URL (
identification-url). - You redirect the User to the
identification-url. - The User follows the step-by-step live verification process, hence uploading the document.
- Treezor keeps you informed of the documents processing with the KYC Liveness webhooks.
- Once the
kycliveness.updatewebhook returns akyc-statusset toprocessed, you may request a KYC review:
a. Retrieve the documents –/v1/users/{userId}/Kycliveness
b. Request a KYC review –/v1/users/{userId}/Kycreview - Treezor sends you the
user.kycreviewwebhook 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.
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)
Click to see the Certified video steps for your end users (mobile)
After the last step:
- The user is redirected to the
redirectUrlor the URL configured with Treezor. - Treezor sends you a
kycliveness.createwebhook with akyc-statusset toprocessing.
# 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.
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:
# Request the download URL
To request the 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 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:
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 |