Qualified Electronic Signature Integration

Integration guide

App Drop-in guide

This guide provides step-by-step instructions on how to integrate Qualified Electronic Signature with the App Drop-in.

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


Flow

Click to magnify

Qualified Electronic Signature App Drop-in flow

Qualified Electronic Signature App Drop-in flow



1. Authenticate

Create an access token to authenticate in our API:

  • You provide your Fourthline API key.
  • 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, make another Create access token request.


2. Create workflow

Create a Qualified Electronic Signataure 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: 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:

FlowStatus
Completed verificationcompleted with a risk score of 200400 (not 500)
Pending verificationnew, pending, or completed with a risk score of 200400 (not 500)

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

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

StatusDescriptionAction
pendingThe client is eligible for a signature.Wait.
kyc_requiredThe 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.
  • A successful response is empty.

API Reference – Upload documents to sign

Status: The signature status remains pending.


4. Upload mobile number

Upload the client's mobile phone number for them to receive the passcode SMS to confirm the signature:

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

API Reference – Upload mobile phone number

Status: The signature status remains pending.


5. Create SDK session

Create the App Drop-in session:

  • You provide the workflowId.
  • You receive a validationCode to pass to the SDK in your backend.

API Reference – Create SDK session

Important
• SDK validation codes are single use and expire after 2 hours.
• If the client stops in the middle of the workflow, you need to create a new SDK session.
• When the client closes the app, the validationCode is invalidated and cleared from the cache.

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

StatusDescriptionAction
signedThe signed documents are available.Download the signed documents.
kyc_requiredThe client didn't pass one or more eligibility checks.Create a new workflow that includes IDV and QES.
errorAn error occurred.
If the system can recover after the error, the status changes to a previous status.
If the system can't 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

Success
Success
You have integrated Qualified Electronic Signature for your app!

Top of page