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 | |
|---|---|
| Description | The signature flow starts while the Identity Verification case is being processed. |
| Benefit | The user experience is smoother as the client can continue the signature flow immediately after the Identity Verification flow, without waiting for case processing. |
| Trade-off | The client may need to re-do the signature flow if inconsistent data is identified during case processing. |
| Configuration | If 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
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 | |
|---|---|
| Description | The signature flow starts after the Identity Verification case has been processed. |
| Benefits | The signature flow can only start if the client is eligible, which ensures higher conversion. The QEC data is confirmed in case processing. |
| Trade-off | The 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
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:
| InfoCert | Namirial |
|---|---|
| InfoCert Terms & Conditions | Namirial Terms & Conditions |
| InfoCert Privacy Statement | Fourthline 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.
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 screen | Required |
|---|---|
| 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
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 screen | Required |
|---|---|
| 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 conditions | Fourthline Terms & Conditions |
| Display when | Always before starting the Identity Verification flow |
| Source | Request from implementation manager |
| Responsibility | You display them to the client in your UI. |
| InfoCert | |
|---|---|
| Legal conditions | InfoCert Terms & Conditions InfoCert Privacy Statement InfoCert PKI Disclosure Statement InfoCert legal clauses |
| Display when | Document approval step |
| Source | Get signature details request |
| Responsibility | App 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 conditions | Namirial Terms & Conditions Fourthline Privacy Statement |
| Display when | Document approval step |
| Source | Get signature details request |
| Responsibility | App 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
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:
| QTSP | Agreements |
|---|---|
| Namirial | 6 digits |
| InfoCert | 8 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.
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 type | Code |
|---|---|
| Austrian driving license | AUT-FO-04001 AUT-FO-05001 AUT-FO-05002 |
| Greek identity card | GRC-BO-01001 GRC-BO-01004 |
| Italian driving license | ITA-FO-05001 ITA-FO-05001 |
| Italian paper ID | ITA-BO-03001 ITA-BO-03002 ITA-BO-03003 ITA-BO-03004 |
| UK driving license | GBR-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.
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.
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.
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:
- App UI Customization – Localization
- Web SDK Setup – Localize the UI
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
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:
| Endpoint | Description |
|---|---|
| Test signature flow | Start the signature flow for a test signature with a target status. |
| Get test passcode | Get 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 |
Updated 4 months ago