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, 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

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.

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 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 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.

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}/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