Skip to content

Qualified eSignature (QES) Beta

Some countries (such as Germany) enforce stricter standards on user verification. One way to follow such standards is by using a Qualified Electronic Signature (QES). For Germany, this option requires a SEPA transfer into the user's Wallet as an extra validation step.

Treezor relies on a user verification provider for QES services. In this process, you redirect end users to a URL where they follow the verification steps. The identity document uploaded during these steps is digitally signed according to QES standards.

Gear icon

Configuration – Environment configuration by Treezor

Contact Treezor to use the qualified eSignature feature.

Process

Documents upload QES verification
  1. You initiate QES verification for the User:
    /v1/users/{userId}/qes
  2. Treezor answers with the QES URL (identificationURL).
  3. You redirect the User to the identificationURL
  4. The User follows the step-by-step QES verification process, hence uploading the document.
  5. Treezor informs you of the documents processing with the QES webhooks.
  6. Once the qes.finalized webhook returns a success Result, you may request a KYC review:
    /v1/users/{userId}/Kycreview
  7. Treezor sends you the user.kycreview webhook upon validation or refusal.

Key attributes (webhooks)

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

  • qes.created – Received when the user completes the QES verification process.
  • qes.processing – Received when the QES verification process is under review on the verification provider side.
  • qes.aborted – Received when the user abandons the QES process (see Aborted reasons list for more details).
  • qes.finalized – Received when the verification process is done on the verification provider side, either successful or canceled (see Canceled reasons list for more details).

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

AttributeTypeDescription
resultstringIndicates whether the user was successfully verified on the provider side. Can be:
  • START – The verification process has started.
  • CHECK_PENDING – The user is currently being verified.
  • FRAUD_SUSPICION_PENDING – Further verifications are made due to fraud suspicions.
  • ABORTED – The end user abandoned the QES verification process.
  • SUCCESS – The end user's identity is verified.
  • SUCCESS_DATA_CHANGE – The end user's identity is verified with data adjustments from provider.
  • FRAUD_SUSPICION_CONFIRMED – The user identity is verified and is suspected of committing fraud.
  • CANCELED – The verification couldn't be carried out by the provider.
reasonobjectDetails about the result when necessary. See Reasons list below.

Reasons

The reason object of the webhook contains a reasonCode and a reasonMessage for you to better understand the result of the QES verification.

Aborted reasons

Here are the reasons you may find for aborted QES.

CodeMessageDescription
3001USER_CANCELLATION_DOCUMENT_NOT_ACCEPTEDUser's ID document is not accepted for the verification process
3002USER_CANCELLATION_DOCUMENT_EXPIREDUser cannot continue the verification process due to an expired ID document
3003USER_CANCELLATION_UNDERAGEUser is underage and is not allowed to continue the verification process
3004USER_CANCELLATION_CAMERA_ACCESS_DENIEDUser does not allow camera permission in the app
3005USER_CANCELLATION_TERMS_DENIEDUser does not accept the terms and conditions
3006USER_CANCELLATION_SELFIE_NOT_READYUser is not ready for a selfie
3007USER_CANCELLATION_APP_NOT_SCANNINGUser aborts as the app is not scanning the document
3008USER_CANCELLATION_ESIGNING_REJECTEDUser does not accept the esigning request
3009USER_CANCELLATION_ESIGNING_NAME_CONFIRMATION_REJECTEDUser's name is specified incorrectly (This applies only to the QES/Signing flow)
3010USER_CANCELLATION_INCORRECT_PHONE_NUMBERUser cancels as the phone number is specified incorrectly
3011USER_CANCELLATION_IDENTIFY_LATERUser wants to identify later
3012USER_CANCELLATION_USER_NOT_INTERESTEDUser is not interested in performing the identity verification
3013USER_CANCELLATION_APP_NOT_RESPONDINGUser aborts because the app is not responding
3014USER_CANCELLATION_PRIVACY_CONCERNSUser aborts due to privacy concerns
3015USER_CANCELLATION_DOCUMENT_NOT_AVAILABLEUser does not have the ID document available and aborts
3016USER_CANCELLATION_OTHERUser aborts the identification process in app for any other unspecified reason
3017APP_CANCELLATION_APPROVAL_PHRASE_RETRY_LIMIT_REACHEDThis is used in the QES/esign flow when the app is unable to retrieve the approval phrases from the backend after multiple retries
3018APP_CANCELLATION_APPROVAL_PHRASE_NO_CONTRACTApp encounters a technical error in the Approval Phrases step in QES/esign
3019APP_CANCELLATION_APPROVAL_PHRASE_INSUFFICIENT_DOCUMENT_COUNTIn the Approval Phrases step for QES/esign, the required number of documents to be signed are not received from backend
3020APP_CANCELLATION_OTP_MATCH_LIMIT_REACHEDIn the OTP Authentication step, the user has reached the allowed limit for number of OTP entries and cannot try again
3021APP_CANCELLATION_TSP_TECHNICAL_EXCEPTIONApp encounters a technical error from the TSP side. If this error state does not resolve after multiple automatic retries, the user cannot proceed further and the ident is aborted with this reason

Canceled reasons

Here are the reasons you may find for canceled QES.

CodeMessageDescription
3101ID_BLURRYDocument is blurry and mandatory data cannot be read due to the blur.
3102ID_GLAREDocument has glare and mandatory data cannot be read due to the glare.
3103ID_DARKNESSPictures of the document are dark and it is not possible to read the mandatory data or verify the authenticity of the document.
3104ID_DATA_COVEREDMandatory data is covered by the user while taking the picture
3105ID_PERSPECTIVEDocument is positioned at such an angle that mandatory data cannot be read or document cannot be verified
3106ID_DATAMandatory data cannot be read on the document
3107ID_DATA_OTHERAny other reason due to which mandatory data cannot be read
3108ID_NOT_SUPPORTEDDocument used during the identification is not supported for the customer's use case
3109ID_EXPIREDDocument used during the identification is expired.
3110ID_WRONG_SIDEWrong side of the document is scanned during the process.
3111ID_OUTWORNDocument is worn out. Either data cannot be read out or the document cannot be verified.
3112ID_HAS_STICKERDocument has such stickers which are not acceptable and the document used is considered as damaged document.
3113ID_WRITTEN_ONDocument has text written over it which makes the document not readable or not verifiable. If the sticker is legit one and added by the authorities while issuing the document then the document will be acceptable and not cancelled due to this reason.
3114ID_BROKENDocument used during the identification is broken.
3115ID_DAMAGEDDocument used during identification is a damaged document.
3116ID_DAMAGED_OTHERAny other reason for a damaged document.
3117ID_SECURITY_FEATURE_NOT_VISIBLE_NOT_FRAUDSecurity features of the document are not visible because user did not move the document correctly.
3118ID_SECURITY_FEATURE_VIDEO_SHORTSecurity feature video is too short to detect if there are holograms in the document.
3119ID_SECURITY_FEATURE_VIDEO_CANNOT_BE_PLAYEDSecurity feature video cannot be played for the agent to review holograms.
3120ID_SECURITY_FEATURE_OTHERAny other issues with the security feature video.
3121ID_SECOND_DOCUMENTIf two documents are required for the identification process, the user needs to photograph two different documents (i.e. ID + Driver's license) - If the second required ID document is not available, the ident will be cancelled.
3122ID_SECOND_DOCUMENT_BAD_PHOTO_QUALITYPhoto quality of the additional document in the process is not acceptable.
3123ID_SECOND_DOCUMENT_DAMAGEDAdditional document used in the identification process is severely outworn, written or drawn on, ripped or broken.
3124ID_SECOND_DOCUMENT_EXPIREDAdditional document used in the identification process is an expired document.
3125ID_SECOND_DOCUMENT_OTHERAny other issues with the additional document used in the identification process.
3126ID_NEED_ADDITIONAL_DOCUMENTAdditional document like Driver's License is missing in the identification process but it was required.
3127ID_OTHERAny other issues with the document used in the identification process.
3128USER_INVOICE_MISSINGCustomer needs proof of address from the user as the additional document but user did not provide it in the identification process.
3129USER_OBSCUREDUser has covered the face during the face comparison process unintentionally like wearing the face mask.
3130SELFIE_BLURRYSelfie taken by the user is blurry and cannot be used to compare the face with the identification document.
3131SELFIE_GLAREPhoto of the user on the ID document has glares and selfie cannot be compared with it.
3132SELFIE_DARKNESSSelfie taken by the user is too dark to compare the face of the person with the photo on the identification document.
3133SELFIE_PERSPECTIVESelfie taken by the user is on such an angle that it is not possible to compare it with the photo on the identification document.
3134SELFIE_OTHERAny other issues with the selfie which restrict ident specialist to compare the selfie of the user with the photo on the identification document.
3135IDENT_CANNOT_BE_COMPLETEDDue to a technical reason, ident specialist cannot finish the identity verification process.
3136IDENT_DISPLAY_ERRORDue to a technical reason, ident specialist cannot see the data submitted by the user in the identification process.
3137IDENT_OTHERAny other reason due to which the identification process cannot be completed by the ident specialist.
3138TSP_WRONG_CONFIRMATION_TOKENA wrong signing code was entered by the user during the signing step.
3139TSP_SIGNING_FAILEDThe signing process failed due to any technical error.
3140TSP_CERTIFICATE_EXPIREDSigning certificates are valid for an hour. The final signing step took more than an hour from the time of certificate generation.
3141ID_SECURITY_FEATURE_VIDEO_FILE_MISSINGIf enabled, the system automatically cancels an ident when the 'Security Features' (Hologram) video is not saved due to any technical error, and is hence missing from the final result (zip) file.

Fraud suspicion reasons

Warning icon

Important – Don't communicate fraud suspicion to end users

For legal reasons, you mustn't indicate to end users that they are suspected of fraud.

Here are the reasons you may find for fraud suspicions.

CodeMessageDescription
3201WARNING_SELFIE_REAL_PERSONUser that performed the identification is a real person but the selfie does not match with the face on the document.
3202WARNING_SELFIE_NO_REAL_PERSONSelfie taken in the identification person is not of a real person. For example, the selfie taken is a photo of a picture.
3203WARNING_SELFIE_DISGUISEDUser intentionally disguised the face by wearing a mask or in some other way.
3204WARNING_MANIPULATED_DATAData is manipulated on the Identification document.
3205WARNING_MANIPULATED_PHOTOPhoto of the person is manipulated on the Identification document.
3206WARNING_FAKED_SECURITY_FEATURESSecurity features like holograms on the Identification document are not real.
3207WARNING_PAPER_PRINTThe Identification document is not real but a printout taken on a paper.
3208WARNING_DIGITAL_DOCUMENTIdentification document image is taken from a digital screen (from laptop, from mobile or from any other screen).
3209WARNING_FAKED_SPECIMENIdentification document is a specimen document and not real document.
3210WARNING_USER_UNDERAGEUser is below the age required to access the customer's service.
3211WARNING_DIGITAL_SELFIESelfie is taken from a digital screen (from laptop, from mobile or from any other screen).
3212WARNING_MONEY_MULEUser is duped by fraudster to perform identification on fraudster's behalf.
3213WARNING_NAME_COMPARISONConsiderable inconsistency between user's name and document.
3214WARNING_SCANIdentification document is a facsimile.
3215WARNING_FRAUD_OTHERAny other type of fraud identified during the verification process by Ident specialist.

Initiate QES verification

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

At least the firstname, lastname, email, country, and phone fields 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 QES verification.

AttributeTypeDescription
redirectUrlstringThe URL to which the User will be redirected after the QES verification.

Request

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

bash
curl -X POST {baseUrl}/v1/users/{userId}/qes \
	--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 identificationURL. The latter is where the end user is to be redirected to go through the qualified electronic signature process.

json
{
   "identification": {
       "identificationId": {{identification-id}},
       "identificationURL": "https://go.idnow.de/app/treezoramlauto/identifications/{{identification-id}}/identification/routing/start",
   }
}

Once redirected, end users are guided through the QES verification steps, in which they present a verification document.

End user QES verification

Once redirected, end users are guided through the QES steps.

Click to see the Qualified eSignature steps for your end users (mobile)QES user steps 1QES user steps 2QES user steps 3

After the last step:

  • The user is redirected to the redirectUrl or the URL configured with Treezor.
  • Treezor sends you a qes.created webhook.
  • The verification documents are automatically created once the qes.finalized webhook is received.

Download the QES 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 download URL, you need the corresponding documentId (available in the document.create webhook for instance).

bash
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 presigned URL has been generated in the previous step.

bash
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:

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

EndpointScope
/v1/users/{userId}/Kycreview
Initiate the user KYC review process
read_write
/v1/users/{userId}/qes
Initiate the user QES verification process
read_write
/v1/documents/{documentId}/download
Retrieve a document download URL
read_only