Qualified Electronic Signature Integration

Integration guide

Setup

This page provides guidance on preparing to integrate Qualified Electronic Signature via the App Drop-in, Web SDK, or the API.

Before you begin your integration, make sure you have the following in place:

Prerequisites

  • You need your Fourthline API key.
  • The client must have a pending or successfully completed Identity Verification case with Fourthline.
  • Agree with your implementation manager the identifiers of your product and market-specific workflows. For default options, see Create workflow.

Statuses

Set up handling for Qualified Electronic Signature statuses.

Webhook

Set up a webhook and handle Qualified Electronic Signature notifications.


Configuration

Discuss with your implementation manager the following configuration options:

Signature flow

Required

In general, we recommend configuring the pending verification flow:

Pending verification
DescriptionThe signature flow starts while the Identity Verification case is being processed.
BenefitThe user experience is smoother as the client can continue the signature flow immediately after the Identity Verification flow, without waiting for case processing.
Trade-offThe client may need to re-do the signature flow if inconsistent data is identified during case processing.
ConfigurationIf you use Web SDK integration, you can ensure the client always finishes the signature flow even if the associated Identity Verification case is unsuccessful, e.g.: case status inconsistent_data, invalid_data, or completed_unacceptable_risk.

This offers a more cohesive user experience than discontinuing the signature flow.

With your implementation manager, configure to delay triggering signature status kyc_required until after reaching pending_verification status.

The pending verification flow is as follows:
Click to magnify

Pending verification flow

Pending verification flow


If many ID documents in your target market don't contain an MRZ or require careful analysis, we recommend the completed verification flow:

Completed verification
DescriptionThe signature flow starts after the Identity Verification case has been processed.
BenefitsThe signature flow can only start if the client is eligible, which ensures higher conversion.
The QEC data is confirmed in case processing.
Trade-offThe client must wait for the case to be processed before they can start the signature flow.

The completed verification flow is as follows:
Click to magnify

Completed verification flow

Completed verification flow



QTSPs

Required

Fourthline uses 2 QTSPs (Namirial and InfoCert) to ensure a fallback option is in place. If one QTSP's service goes down temporarily, clients are automatically redirected to the other to maintain conversion and a smooth user experience.

There are the following differences between the QTSPs:

  • Legal conditions
  • InfoCert contract
  • One-time passcode

Legal conditions

Clients must accept the following legal conditions per QTSP:

InfoCertNamirial
InfoCert Terms & ConditionsNamirial Terms & Conditions
InfoCert Privacy StatementFourthline Privacy Statement
InfoCert PKI Disclosure Statement
InfoCert legal clauses

For SDK integration, Fourthline's UI dynamically displays the relevant legal conditions per QTSP on the Document approval screen.

Document approval screen

Fourthline UI: Document approval screen

If using API-only integration and your own UI, the relevant QTSP legal conditions for a specific signature flow are returned in the Get signature details response. The following requirements apply:

Document approval screenRequired
Dynamically display the QTSP legal conditions, which the client must actively accept and be able to download.
Display InfoCert's legal clauses, which the client must actively accept.

InfoCert contract

InfoCert generates a personalized contract for the client, which you must download via a Get InfoCert contract request and share with the client.

One-time passcode

Namirial's one-time passcode is 6 digits long and InfoCert's 8 digits long.

For SDK integration, Fourthline's UI dynamically displays the relevant number of passcode digits per QTSP on the Signature confirmation screen.

Fourthline UI: Signature confirmation screen

Fourthline UI: Signature confirmation screen

For API-only integration, the relevant QTSP passcode length for a specific signature flow is returned in the Get signature details response. The following requirements apply:

Signature confirmation screenRequired
Display the titles of the documents to sign.
Dynamically change the passcode mask to the right number of digits per QTSP.


Legal conditions

Required

The client must accept the following legal conditions per party:

Fourthline
Legal conditionsFourthline Terms & Conditions
Display whenAlways before starting the Identity Verification flow
SourceRequest from implementation manager
ResponsibilityYou display them to the client in your UI.

InfoCert
Legal conditionsInfoCert Terms & Conditions
InfoCert Privacy Statement
InfoCert PKI Disclosure Statement
InfoCert legal clauses
Display whenDocument approval step
SourceGet signature details request
ResponsibilityApp Drop-in & Web SDK: Fourthline displays them to the client in our UI.
App Components & API: You display them to the client in your UI.

Namirial
Legal conditionsNamirial Terms & Conditions
Fourthline Privacy Statement
Display whenDocument approval step
SourceGet signature details request
ResponsibilityApp Drop-in & Web SDK: Fourthline displays them to the client in our UI.
App Components & API: You display them to the client in your UI.

Legal conditions language

When retrieving legal conditions via the Get signature details request, you can also optionally specify the language:

  • Dutch
  • English (default)
  • French
  • German
  • Italian
  • Polish
  • Romanian
  • Spanish
Important
This also sets the language of the passcode SMS.

One-time passcode

Required

When the client confirms the signature, the QTSP sends them a one-time passcode via SMS.

The number of passcode digits differs per QTSP:

QTSPAgreements
Namirial6 digits
InfoCert8 digits

The SMS can be sent in the following languages:

  • English (default)
  • French
  • German
  • Italian
  • Polish
  • Romanian
  • Spanish

You can specify the SMS language in the Get signature details request.

Important
This also sets the language of the legal conditions.

ID documents

Required

The following ID documents don't contain an MRZ, which in the pending verification flow can lead to invalid_signature status. This is because we extract the details for the certificate from the VIZ, which is less reliable.

Decide with your implementation manager if you want to support the following documents or not.

Document typeCode
Austrian driving licenseAUT-FO-04001 AUT-FO-05001 AUT-FO-05002
Greek identity cardGRC-BO-01001 GRC-BO-01004
Italian driving licenseITA-FO-05001 ITA-FO-05001
Italian paper IDITA-BO-03001 ITA-BO-03002 ITA-BO-03003 ITA-BO-03004
UK driving licenseGBR-FO-05001 GBR-FO-05003 GBR-FO-06001 GBR-FO-07001
GBR-FO-08001 GBR-FO-08002 GBR-FO-09001 GBR-FO-09002
GBR-FO-09003 GBR-FP-05001 GBR-FP-06001


Geolocation check

Optional

During the signature flow, check if the client's device metadata is in a prohibited country when you want them to sign documents. The client is only eligible for a signature if they are in a supported country.

If including this check, we recommend using the pending verification flow to avoid clients getting stuck at kyc_required status.

Important
This check is only triggered if the client's most recent Identity Verification case (which includes a geolocation check) was completed more than 24 hours ago.
More information
For the complete list of supported countries and territories, request our CDD Policy from your implementation manager.


Sanctions check

Optional

During the signature flow, check if the client is potentially sanctioned when you want them to sign documents. The client is only eligible for a signature if there are no hits for them in your selected AML database.

If including this check, we recommend using the pending verification flow to avoid clients getting stuck at kyc_required status.

Important
This check is only triggered if the client's most recent Identity Verification case (which includes an AML screening) was completed more than 24 hours ago.

Fourthline can perform the sanctions check via either AML Monitoring or a one-off sanctions check:

AML monitoring

We monitor the client against your selected AML database daily. During the signature flow, we check the client's sanctions status for that day.

If we find a potential hit, we investigate the case. When the investigation is completed, we send you the outcome via a webhook notification.

You always have an up-to-date screening status for the client and can act accordingly, e.g. offboard a sanctioned client.

Tip
Tip
Consider configuring your side to not allow sanctioned clients to start a signature flow.

One-off sanctions check

Screen your selected AML database for potential hits during the signature flow.

Fourthline doesn't perform an investigation. If we find potential hits, the client is ineligible for a signature.


Flow language

Optional

For App Drop-in or Web SDK integration, you can set the language of the signature flow UI when you create the SDK session.

For the supported languages and instructions, see:

If you don't set the UI language or the language isn't supported, the default is English.


Signature position

Optional

You can configure if you want the signature to be visible on signed documents and on which page.

Specify its size and position in PDF units. There are 72 PDF units per inch (") / 2.83 per millimeter (mm), e.g.:

  • US letter page size of 8.5" x 11"= 612 x 792 PDF units
  • A4 page size of 210mm x 297mm= 595 x 842 PDF units
Signature position

Signature position


Configure the signature visibility and position in the Upload documents to sign request.


Testing

We offer the following endpoints for testing signature flows in the sandbox environment only:

EndpointDescription
Test signature flowStart the signature flow for a test signature with a target status.
Get test passcodeGet a one-time passcode to confirm a test signature, without requiring a valid mobile phone number.

Important:
If you have InfoCert configured as one of your QTSPs, you don’t need to make this request because the passcode is the same as the last 8 digits of the mobile phone number.
Example:
• Phone number: +39 11111112222
• Passcode: 11112222

Support
For any questions, contact your implementation manager.

Top of page