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.

Process

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 with a score of 1, 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 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
2404	The applicant has recently performed a fraud attempt

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 understand why a live verification process has been aborted.

The query parameters provided with the redirectUrl are the following:

Parameter	Description
id	The unique identifier of the live verification process.
event	The event that has prompted the redirection.
response_code	The verification provider code, which is different from the reason_code. Please refer to the reason_code available in the webhook for more information regarding the result.

More about the Redirect URL query parameters

If you take the following URL:

redirect_url?id=idv_123&event=identity_verification_capture_aborted&response_code=61101

You can deduce that the identification process idv_123 was aborted due to an error.

Here is the list of events for the query parameters:

• identity_verification_capture_aborted
• identity_verification_link_expired
• identity_verification_capture_refused
• identity_verification_capture_completed

Note: This information is from Treezor's verification provider. Therefore, we cannot guarantee the long-term availability of the value: please rely on the webhooks for your integrations.

Request

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

CURL

curl -X POST '{baseUrl}/v1/users/{userId}/kycliveness' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{"redirectUrl": "https://www.my-domain.tld"}'

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.

JSON

{
    "identification": {
        "identification-id": "f8048bee-3182-48dc-93e5-7eef9db77050",
        "identification-url": "https://id.ubble.ai/f8048bee-3182-48dc-93e5-7eef9db77050",
        "type": "video_certified"
    }
}

Once redirected, end users have 15 minutes to complete the steps for the relevant live verification feature. After this delay, the identification-url expires.

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 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 and a score of 1 (validated), you must retrieve the documents from the live verification provider for them to be uploaded to Treezor.

Detailed score values

Below is the meaning of each value the score attribute of the kycliveness.update can return.

Score	Description
1	Validated. The live verification is processed, and the user was successfully identified.
0	Refused. The live verification is processed, and the live verification provider couldn't verify the user (e.g., expired document).
-1	Failed. The live verification couldn't be properly processed. Can be due to errors, the end user abandoning the process, or failure to present the document for example.

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.

CURL

curl -X PUT '{baseUrl}/v1/users/{userId}/kycliveness' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json'

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:

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

Request the download URL

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

CURL

curl -X GET '{baseUrl}/v1/documents/{documentId}/download' \
	--header 'Authorization: Bearer {accessToken}' \

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

JSON

{
    "url": "{documentDownloadUrl}"
}

Download the document

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

CURL

curl -X GET '{documentDownloadUrl}'

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:

• /v1/users/{userId}/Kycreview

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	Scope
/v1/users/{userId}/kycliveness Initiate the user Live verification process	read_write
/v1/documents/{documentId}/download Retrieve a document download URL	read_only
/v1/users/{userId}/kycliveness Upload the documents once the Live verification is completed.	read_write
/v1/users/{userId}/Kycreview Initiate the user KYC review process	read_write