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

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.