Qualified Electronic Signature Integration

Setup

Mobile SDK

API Guide

Web SDK guide

This guide provides step-by-step instructions on how to integrate Qualified Electronic Signature with the Web SDK.

Before you begin, make sure you have completed the following:

Flow

Click to magnify

Qualified Electronic Signature Web SDK flow

1. Authenticate

Create an access token to authenticate in our API:

You provide your Fourthline API credentials.
You receive an access_token.

API Reference – Create access token

Important

For security, access tokens are valid for 1 hour only.

If your token expires, create a new access token by making another Create access token request.

2. Create workflow

Create a Qualified Electronic Signature workflow:

You specify the workflowName and provide your unique identifier for the client.
You receive a workflowId and a Fourthline clientId.

API Reference – Create workflow

Status Status: The signature status changes to new and we send the relevant webhook notification.

Fourthline checks that the status of the related Identity Verification case is one of the following:

Flow	Status
Completed verification	`completed` with a risk score of `200` – `400` (not `500`)
Pending verification	`new`, `pending`, or `completed` with a risk score of `200` – `400` (not `500`)

If the Identity Verification case status is valid, we perform the initial ID document check, and (if configured) the sanctions check.

Status Status: The signature status changes to one of the following and we send a webhook notification:

Status	Description	Action
`pending`	The client is eligible for a signature.	Wait.
`kyc_required`	The client didn't pass one or more eligibility checks.	Create a new workflow that includes `IDV` and `QES`.

3. Upload documents to sign

Upload to Fourthline the document(s) you want the client to sign:

You provide the workflowId, information about the documents, and the files.
Documents can be uploaded in parallel as long as each document uses a unique document_id.
Requests around 26 MB may hit the default request size limit.
For optimal reliability and experience, we recommend keeping the number of documents per signature low (typically two or three).
A successful response is empty.

API Reference – Upload documents to sign

Status Status: The signature status remains pending.

4. Upload mobile number

Upload the client's mobile phone number:

You provide the workflowId and the phone number.
A successful response is empty.

API Reference – Upload mobile phone number

Status Status: The signature status remains pending.

5. Create SDK session

Create the Web SDK session:

You provide the workflowId.
You receive an 8-digit, alphanumerical validationCode to pass to the SDK in your backend.

If the client starts on your website in their:

Desktop browser: Initialize the Web SDK, display the redirect options, and redirect the client to the workflow in their mobile browser.
Mobile browser: Display the redirect options and then redirect them to the workflow on your subdomain.

API Reference – Create SDK session

Important

SDK validation codes are single-use and expire after 2 hours.

If the client stops partway through the workflow, create a new SDK session.

When the client closes the browser, the validationCode is invalidated and removed from the cache.

Status Status: The signature status changes to one of the following and we send a webhook notification:

Status	Description	Action
`signed`	The signed document(s) are available.	Download the signed documents.
`kyc_required`	The client didn't pass one or more eligibility checks.	Create a new workflow that includes `IDV` and `QES`.
`error`	An error occurred. If the system can recover after the error, the status changes to a previous status.	If the system cannot recover, create a new workflow for a signature only.

Check signature status

When you receive webhook notifications, we recommend also checking the signature status:

You provide the signatureId (same value as the workflowId).
You receive the current status and status code.

API Reference – Get signature status

6. Download signed documents

When the signature status is signed, download each signed document:

You provide the signatureId (same value as the workflowId) and relevant documentId.
You receive a message in plain text and the PDF document.

API Reference – Get signed document

If you have the fallback QTSP option configured, check if an InfoCert contract was generated, which you are required to download and share with the client:

You provide the signatureId (same value as the workflowId).
You receive one of the following empty responses:
- 200: The signature flow was directed to InfoCert and the response returns the contract to share with the client.
- 204: The signature flow was directed to Namirial so no contract is returned.

API Reference – Get InfoCert contract