Create a new fidentity process

The most important things about the creation of a new fidentity process:

Authorizations

How long is the JWT token valid?

4 hours

Customer

Can “customer” contain empty strings?

No, missing information in form of empty strings will cause negative scores during validation. To disable input validation, set customer to null{}.

Are there mandatory fields for QES?

There are two options for QES:

• Customer is empty customer: { }

• Customer has name, firstname, dateOfBirth and nationality.

Can multiple nationalities be posted?

No, it is only possible to post one nationality.

What country codes do you use?

We use ISO 3166-1 alpha-3 codes. A list can be found in our documentation https://demo.fidentity.ch/docs under fidentity/Create a new fidentity process/customer/nationality.

ProcessSteps

Types

Type	Description
Selfie	Liveness detection in three steps to verify the user's identity.
DocumentRegistration	Scanning of configured identification documents for identity verification.
AgentReview	Applicable only upon prior agreement. Routes processes with a low score to manual agent review.
UserReview	Users are presented with extracted names for correction. Must be combined with "DocumentRegistration."
QesSignature	For qualified electronic signatures (QES). Only available for configured tenants.
Signature	For advanced electronic signatures (AES).
Welcome	Displays an introduction screen with general identification tips.
PdfScan	Allows users to take a photo, which is then provided as a PDF.
PersonalData	Only available upon prior agreement and configuration. Enables custom user forms.
HandwrittenSignature	To be used in combination with QES. Allows the user to draw a signature, which is provided as an image.
Info	Reserved for change requests and applicable only upon agreement with fidentity.

Subtypes

Subtype	Description
main	Default subtype. Can be used with all process steps.
nfc	Prompts the user to read the NFC chip from their identification document. Only passports are accepted. This subtype must only be used with "DocumentRegistration."
zoom	Only available upon prior agreement and as a change request.
readonly	Only available upon prior agreement and as a change request.
api	Only available upon prior agreement and as a change request.
identOnly	Must only be used with the type "QesSignature." Triggers a QES identification.
signOnly	Must only be used with the type "QesSignature." Triggers the signature process for the associated identification process.
singleRun	Must only be used with the type "QesSignature." Triggers a temporary QES identification without WebAuthn.

What is the attribute “key” used for in a process step?

This attribute is optional and can be used for identification when returning the status. The value can be defined by the customer and ideally is unique for each process.

What is the “welcome” process step used for?

This ProcessStep is provided for special cases. Please do not use it.

How is the “main” attribute used correctly?

For identification via NFC, the subtype “nfc” must be set for DocumentRegistration. Otherwise “main” should always be used.

Example Selfie with NFC

  "processSteps": [ 
    {
      "type": "Selfie",
      "subtype": "main"
    },
     {
      "type": "DocumentRegistration",
      "subtype": "nfc"
    }],

How can the QES process be set up correctly?

When creating a Qualified Electronic Signature (QES), set “QesSignature” as type and “main” as the subtype. This ensures that all necessary steps, including Selfie, DocumentRegistration, NFC scans Signature are included in the process.

Example QES

"processSteps": [
    {
      "type": "QesSignature",
      "subtype": "main"
    }],

SystemUrls

What do the states mean?

State	Description	Note
started	Process was started / User clicked on link
error	User failed the process	Not applicable to QES
sucess	Process succeeded
warn	User finished the process un- nor successful.	Not applicable to QES
abort	User aborted the process	Is triggered when clicking on (x)
session-expired	Process URL has expired	Triggered when the JWT token expires and for incomplete processes

What data is passed in the callback?

The extId is posted to the callback URLs ex. { extId: ”…” }

How can systemUrls be set up correctly?

Following example payload counts for all types:

"systemUrls": [
    {
      "url": "https://webhook.site/abcd-0000-1111-2222-3333",
      "type": "callback",
      "state": "success"
    },

What happens if the “callback” URLs are not accessible?

A retry mechanism for the callbacks is missing so far and would have to be ensured on the customer side (queue etc.). With the callbacks, we call the customer backend. The integrator ensures that the endpoint is always reachable.

DocumentUris

How should documentID be set?

Same as Cutsomer ID ^[A-Za-z0-9-.]{10,60}$ (no space between elements).

Does the documentID have to be unique?

Multiple documents in the same process can’t have the same ID. The documentID only has to be unique in the current process.

What is type meant for?

Document type, uri and ID help you identify the document after signing. “Signature” is set on default but you can also different terms like “contract”

Are all PDF formats allowed for QES signature?

No, only PDF/A is allowed. The requirement to have a valid and standard conform PDF (PDF/A) comes from our signing infrastructure.

Can you recommend a PDF/A converter?

We can recommend these converters:

• https://www.ghostscript.com/
• https://github.com/matteosecli/pdf2archive
• https://verapdf.org/

Are there any other restrictions for QES PDFs?

The document should be no larger than 2MB and contain a maximum of 30 pages.