Fourthline KYC

This guide describes the integration process of the Fourthline KYC method as a stand-alone solution, including key concepts, the mandatory information you must collect from your customers, and the necessary endpoints and webhooks you must integrate into your solution.

Introduction

Product overview

Fourthline is a semi-automated KYC for identifying your customers according to KYC guidelines. It combines taking a selfie, scanning an ID document, and collecting metadata, such as geolocation. Solaris offers this solution through mobile and web SDKs and a simple set of API calls. Additionally, you can integrate Fourthline as a standard KYC method or combine it with a QES (Qualified Electronic Signature) to enable your customers to securely sign contracts.

Eligibility

You can use Fourthline as a KYC method for any of Solaris' products, including high-risk banking products, such as a full bank account. However, Fourthline cannot be used as a KYC method for customers in Germany.

Additionally, depending on the branch and your use case, it might be mandatory to combine Fourthline with a QES (Qualified Electronic Signature). Solaris team will help you choose the KYC method suitable for your banking use case.

User journey

Customers can identify themselves via Fourthline in three simple steps. The following steps explain the KYC flow the customer will go through with IDnow:

1. Data collection

  1. The customer enters the required personal data (name, address, mobile number, nationality, and birth date).
  2. Solaris sends an SMS OTP to the customer's mobile number, and the customer must enter this OTP to verify their number.

2. ID document scan

The customer scans their ID document. During the process, Fourthline performs:

  • Automatic data extraction from the machine-readable zone
  • Verification of holograms and other security features
  • Tampering and counterfeit detection
  • Real-time feedback to the customer to improve photo quality

3. Selfie

The customer takes a selfie according to the instructions from Fourthline. During the process, Fourthline performs:

  • Fraud detection and face checks with alert lists
  • Real-time feedback to the customer to improve photo quality

4. Qualified Electronic Signature (optional)

The customer reviews and approves any documents to be electronically signed by receiving and confirming a one-time password (OTP) via SMS. During the process:

  • The customer reviews any documents to be signed.
  • The customer requests an SMS OTP to be sent to their verified mobile number.
  • The customer enters the SMS OTP to sign the relevant documents.
  • The customer downloads or receives via email the signed documents.

System prerequisites

Before starting the Fourthline identification process, you must implement the following requirements:

1. Technical setup:

Set up your environment and get your authentication keys. For step-by-step instructions, check the Technical setup guide.

2. Legal and compliance screens:

Build the necessary legal and compliance screens in your sign-up flow to collect your customers' consent to the necessary legal and compliance requirements. The Legal and compliance screens guide contains step-by-step instructions on how to create these screens and what they must contain.

Record the customer's consent on each screen as a UTC timestamp (e.g., 2019-01-01T00:00:00Z). Afterward, you must pass each timestamp in its respective field to Solarisbank.

  • Collect the customer's consent to Solarisbank's Terms and Conditions and store the timestamp in the terms_conditions_signed_at field.
  • Collect the customer's consent to data processing and store the timestamp in the data_terms_signed_at field.
note

The mentioned fields are part of the person resource in which all the customer data points are stored.


Webhooks

Solaris recommends subscribing to the following webhook events to better automate your processes. For detailed instructions on implementing Solaris webhooks, check the webhooks documentation.


Integration overview

The following sequence diagram gives an overview of the integration flow for the Fourthline solution:

Diagram: Fourthline integration flow

You can integrate Solaris' Fourthline product by completing the 7 steps explained in the following sections. Here's an overview of these steps:

Customer registration

In this phase of the integration process, you must collect all the relevant data points from your customer and create the required resources on Solaris' side by doing the following:

  1. Collect the mandatory customer data and consent to the legal and regulatory requirements in your sign-up flow, and create a person resource for your customer by completing Step 1.
  2. Create and verify the customer's mobile number by completing Step 2.

Customer identification resource

In this phase of the integration process, you must create and request identification with Fourthline for the customer by doing the following:

  1. Create an identification resource for the customer on Solaris' side using POST Create identification.
  2. Request an identification for the customer using PATCH Request an identification.

Fourthline identification flow

In this phase, you must integrate Fourthline SDK in your solution and set up the identification flow by doing the following:

  1. Integrate Fourthline SDK.
  2. Set up and initialize the identification flow.
  3. Initiate the Fourthline identification flow on the customer's device.
  4. Store the identification output.

Identification data upload

  1. After the customer successfully completes the identification flow with Fourthline, you must upload the collected KYC data as a .zip file to Solaris by completing Step 5.

Qualified Electronic Signature (optional)

In this phase, if you need to collect a QES from the customer, you must do the following (see Step 6):

  1. Make the documents to be signed available to the customer beforehand to review.
  2. Request an SMS OTP to be sent to the customer's mobile number using PATCH Start QES process.
  3. After the customer enters the SMS OTP on your app, confirm the QES process using PATCH Confirm QES.
note

The QES step may be mandatory for customer identification depending on jurisdictions and your identification use case.

Identification outcome

Track status changes of the identification resource in your backend to see the results of the flow by doing the following:

  1. Register a webhook listener for IDENTIFICATION event to be informed about any identification status changes.
  2. Integrate all the relevant endpoints in Step 7 to retrieve the identification outcome.
  3. Check the results of the identification to determine next steps:
  4. If the identification is successful, continue with the onboarding of your customer.
  5. If the identification has failed, check the failure reason and type. Depending on the failure reason, you can either allow the customer to retry the identification flow (e.g., advise the customer use better lighting if the identification failed due to poor image quality), or abort the onboarding process for the customer in case of suspected fraud.

You can find detailed descriptions of these steps and their related endpoints in the following sections.

note

If you want to use Fourthline as the KYC method in another integration flow of any of Solaris' products (e.g., there's an existing person resource and verified mobile number for the customer), you can jump to Step 3.


Step 1: Collect customer data and create person resource

In this step, you must collect the mandatory data points from the customer in your sign-up flow, including all the timestamps of the customer's consent to the legal and compliance screens. Afterward, pass all the data points to Solaris by creating a person resource.

What is a person resource?

The person resource represents the customer's personal and financial data at Solaris. It contains all mandatory customer data, as well as links to other resources created for the customer (e.g., accounts, tax identifications).

API reference

Visit the following link to find all the endpoints related to the person resource, including related properties and examples.

Related webhook events

Important points about the person resource
  • The mandatory data points for this endpoint depend on various factors, such as the product, customer type (e.g., retail customers, freelancers, legal representatives, or beneficial owners), and country.
  • You must submit the information exactly as it appears in official documents.
  • Solaris validates the values entered for the fields first_name and last_name. Please ensure your solution applies the following sanitization rules to these fields:

    • It must not be longer than 50 characters.
    • It must not start with a whitespace.
    • It must not include any symbols or emojis.
  • When testing this process on Sandbox, please ensure that you create as many unique person resources as possible (i.e., unique values for first_name, last_name, birth_city, and birth_date). If you create more than 1000 identical person resources, then the API will return a 400 error.

Note about branching

Solaris may restrict the residency countries that are allowed for customers onboarding to a specific branch. If you attempt to create a customer with a residency country that is not allowed for the given branch, the API will return a 400 error and provide a list of allowed residency countries.

Example:

Copy
Copied
{
    "errors": [
        {
            "id": "24b0e02a-341d-40bc-9e52-0d9f8cc8c6eb",
            "status": 400,
            "code": "invalid_model",
            "title": "Invalid Model",
            "detail": "country Residency Country is not allowed for this branch,allowed residency country values for branch \"null\" are [\"DE\", \"FR\"]",
            "source": {
                "field": "country",
                "message": "Residency Country is not allowed for this branch,allowed residency country values for branch \"null\" are [\"DE\", \"FR\"]"
            }
        }
    ]
} 

Please contact your Partner Manager for information about which residency countries are allowed for your branch(es).

POST Create person

This endpoint creates a person resource for your customer. You must collect the mandatory data points from your customer in the sign-up flow and pass them to Solaris in the request body of this endpoint.

  • salutation
  • first_name (including all middle names as printed on the ID document)
  • last_name (including all name parts as printed on the ID document)
  • birth_date
  • nationality ISO 3166-1 alpha-2 codes
  • address (Street, Number, City, Post Code, Country, State)
  • mobile_number
  • data_terms_signed_at (UTC timestamp)
  • terms_conditions_signed_at (UTC timestamp)
attention

Please note that Solaris validates the values entered for the fields first_name and last_name. Please ensure your solution applies the following sanitization rules to these fields:

  • It must not be longer than 50 characters.
  • It must not start with a whitespace.
  • It must not include any symbols or emojis.

Request URL

Copy
Copied
POST /v1/persons
{
  "salutation": "MS",
  "first_name": "Jane",
  "last_name": "Doe",
  "address": {
    "line_1": "Amrumerstrasse",
    "line_2": "14",
    "postal_code": "13353",
    "city": "Berlin",
    "country": "DE"
    },
  "mobile_number": "+49301234567",
  "birth_date": "1992-12-11",
  "nationality": "DE",
  "terms_conditions_signed_at": "2022-01-01T00:00:00.000Z",
  "data_terms_signed_at": "2022-01-01T00:00:00.000Z"
}

Response example

The API returns a person object with a unique ID for the person (i.e., the person_id). You will need this id to append the person resource with additional information in the remaining steps of this guide.

Copy
Copied
200 Created
{
    "id": "7cf09c3c5547b974a664201f24b454eecper",
    "salutation": "MS",
    "title": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "address": {
        "line_1": "Amrumerstrasse",
        "line_2": "14",
        "postal_code": "13353",
        "city": "Berlin",
        "country": "DE",
        "state": null
    },
    "contact_address": {
        "line_1": null,
        "line_2": null,
        "postal_code": null,
        "city": null,
        "country": null,
        "state": null
    },
    "email": null,
    "mobile_number": "+49301234567",
    "birth_name": null,
    "birth_date": "1992-12-11",
    "birth_city": null,
    "birth_country": null,
    "nationality": "DE",
    "employment_status": null,
    "job_title": null,
    "tax_information": {
        "tax_assessment": null,
        "marital_status": "UNKNOWN"
    },
    "fatca_relevant": null,
    "fatca_crs_confirmed_at": null,
    "business_purpose": null,
    "industry": null,
    "industry_key": null,
    "terms_conditions_signed_at": "2022-01-01T00:00:00.000Z",
    "own_economic_interest_signed_at": null,
    "aml_follow_up_date": "2029-01-22",
    "aml_confirmed_on": "2022-07-22",
    "flagged_by_compliance": false,
    "expected_monthly_revenue_cents": null,
    "vat_number": null,
    "website_social_media": null,
    "business_trading_name": null,
    "nace_code": null,
    "business_address_line_1": null,
    "business_address_line_2": null,
    "business_postal_code": null,
    "business_city": null,
    "business_country": null,
    "business_state": null,
    "screening_progress": "NOT_SCREENED",
    "risk_classification_status": "NOT_SCORED",
    "customer_vetting_status": "NOT_VETTED",
    "annual_income_range": null,
    "data_terms_signed_at": "2022-01-01T00:00:00.000Z",
    "branch": null,
    "birth_province": null,
    "birth_post_code": null,
    "socioprofessional_category": null,
    "purpose_of_account_opening": null,
    "main_income_source": null,
    "work_country": null,
    "work_province": null,
    "self_declared_as_pep": null,
    "international_operativity_expectation": [],
    "registration_number": null,
    "legitimation_valid_until": null
}

Click here to view the full API reference

PATCH Update person

This endpoint updates one or more properties on a person resource. You can only update the following properties using this endpoint:

  • title
  • salutation
  • address (line_1, line_2, postal_code, city, state, country)
  • contact_address (line_1, line_2, postal_code, city, state, country)
  • employment_status
  • job_title
  • email
  • tax_information (tax_assessment, marital_status)
  • fatca_relevant
  • fatca_crs_confirmed_at
  • business_purpose
  • industry
  • industry_key
  • own_economic_interest_signed_at
  • aml_confirmed_on (only with today or tomorrow's date)
  • expected_monthly_revenue_cents
  • vat_number
  • website_social_media
  • business_trading_name
  • nace_code
  • business_address_line_1
  • business_address_line_2
  • business_postal_code
  • business_city
  • business_country
  • annual_income_range
  • data_terms_signed_at
  • branch
  • birth_province
  • birth_post_code
  • socioprofessional_category
  • purpose_of_account_opening
  • main_income_source
  • work_country
  • work_province
  • self_declared_as_pep
  • international_operativity_expectation
  • registration_number
attention
  • Fields not mentioned in this list can only be updated via Customer Support.
  • Only for B2C customer: If a customer changes their employment_status to FREELANCER or SELF_EMPLOYED, please note that you must do one of the following options in the same request to avoid getting an error:

    1. Collect the nace_code from the customer, or
    2. Set the fields industry and industry_key to null.
  • It's recommended to collect the nace_code from the customer for data quality.

Request URL

Copy
Copied
PATCH /v1/persons/{id}

Click here to view the full API reference


Step 2: Create and verify mobile number

In this step, you must collect the customer's mobile number in your sign-up flow and then create a mobile number resource and verify it by sending an SMS OTP to the customer's mobile number. Afterward, the customer enters the received OTP in your frontend to verify their number.

Mobile number resource

Creating and verifying a mobile number for your customer is a crucial step in the customer onboarding process. With a verified mobile number, customers can use SMS OTPs to complete two-factor authentication (2FA) challenges, which is a requirement for Strong Customer Authentication (SCA).

info
  • In some use cases (e.g., stand-alone integrations, the mobile number is verified during the identification process).

API reference

Visit the following link to find all the endpoints related to the mobile number resource, including related properties and examples.

Related webhook events

Testing static values

To test the following endpoints on Sandbox, you can use the following static values:

  • Mobile number: +15550101
  • SMS OTP: 212212

POST Create mobile number

Collect the customer's mobile number and pass it to Solaris using the following API call, and include the customer's person_id in the request URL.

Request example:

Copy
Copied
POST /v1/persons/{person_id}/mobile_number
{
  "number": "+15550101"
}

Response example:

The API returns a mobile_number resource with a unique id and attaches it to the person resource.

Copy
Copied
{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": false
}

Click here to view the full API reference.

POST Authorize mobile number

Use the following endpoint to verify the ownership of the provided mobile phone number. The endpoint initiates a one-time-password (OTP) flow: Solaris sends a six-digit OTP to the customer's number, and then they must enter it in your UI.

Request example:

Copy
Copied
POST /v1/persons/{person_id}/mobile_number/authorize
{
  "number": "+15550101"
}

Response example:

Copy
Copied
{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": false
}

Click here to view the full API reference..

POST Confirm mobile number

Use this endpoint to submit the SMS OTP the customer received on their mobile number to finalize the mobile number authorization process. You must add the customer's number and token (i.e., the SMS OTP) in the request body. Afterward, the mobile number will be verified and can be used in the context of Strong Customer Authentication (SCA).

Request example:

Copy
Copied
POST /v1/persons/{person_id}/mobile_number/confirm
{
  "number": "+15550101",
  "token": "212212"
}

Response example:

Copy
Copied
{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": true
}

Click here to view the full API reference.

Mobile number management

For more information about how to manage mobile numbers, check the related guide.


Step 3: Create the identification resource

In this step, you must create an identification resource for your customer on Solaris' side.

API reference

Visit the following link to find all the endpoints related to the different customer identification methods (KYC), including related properties and examples.

note

The previous link includes all endpoints for different KYC methods. This section includes the relevant endpoints required for identification with Fourthline.

POST Create identification

This endpoint creates an identification resource for the person specified in the request URL. Specify the following properties in the request body:

  • method: The identification method to use. If you want to use the standard Fourthline KYC flow, set the value of this field to fourthline. If you want to use Fourthline combined with a QES, set the value to fourthline_signing.
attention

This endpoint does not send a request to the identification provider to start the identification process. The actual identification process is triggered when you call PATCH Request person identification.

Request example

Copy
Copied
POST /v1/persons/{person_id}/identifications
{
  "method": "fourthline"
}

Response example

The API call returns an identification object with a unique id, the identification_id, as well as the identification status, set initially to created.

For a list of possible values for the field status and their descriptions, check the appendix.

Copy
Copied
{
    "id": "a7a57dadfcc83117b5c3b72f4113be25cidt",
    "reference": null,
    "url": null,
    "status": "created",
    "completed_at": null,
    "method": "fourthline",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null
}

Click here to view the full API reference.

GET List supported documents for a person identification

Prior to starting the identification process, you can fetch the supported documents to share it with the customer beforehand.

This endpoint returns an array of document types that a customer may use to identify themselves along with a list of allowed issuing countries. The issuing_countries are provided as ISO country codes (ISO-3166-1 alpha 2). If the customer does not provide a supported document type in the identification process, then their identification will eventually fail.

Request URL

Copy
Copied
GET /v1/persons/{person_id}/identifications/{id}/supported_documents

Response example

Copy
Copied
[
  {
    "type": "Passport",
    "issuing_countries": [
      "ES"
    ]
  }
]

Click here to view the full API reference

PATCH Request person identification

This endpoint requests the identification for the specific customer.

The status of the identification will change to pending after calling this endpoint. Once the identification process finishes, you will receive a notification from the IDENTIFICATION webhook and the status will change to successful or failed depending on the outcome.

Request URL

Copy
Copied
PATCH /v1/persons/{person_id}/identifications/{id}/request

Response example

The API call returns the identification object with the status pending.

Copy
Copied
{
    "id": "a7a57dadfcc83117b5c3b72f4113be25cidt",
    "reference": null,
    "url": null,
    "status": "pending",
    "completed_at": null,
    "method": "fourthline",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null,
    "estimated_waiting_time": null
}

Click here to view the full API reference.


Step 4: Invoke Fourthline SDK

In this step, you must integrate Fourthline SDK into your environment and trigger the identification flow on the customer's device to collect and process the KYC data from the customer.

1. Integrate Fourthline SDK

Fourthline offers native SDKs for iOS and Android. For step-by-step instructions on how to integrate the SDKs, refer to Fourthline's documentation:

note

You need specific credentials and set-up to access Fourthline documentation and the Github repository. Solaris team will share these credentials with you.

2. Set Fourthline flow parameters

After integrating the Fourthline SDK, you must create a KycInfo object, which will be populated by the KYC data during the identification flow.

For more information about the KycInfo object, check the relevant documentation:

How to create the KycInfo object?

When creating the KycInfo object, you must add the following input parameters:

  • <PersonId> = The ID of the person resource you created for the customer on Solaris' side in Step 1.
  • <ProviderName> = Your dedicated static provider name, which the Solaris team will share with you.
iOS/SwiftAndroid/Kotlin
Copy
Copied
  let provider = Provider()
  provider.clientNumber = "<PersonId>"
  provider.name = "<ProviderName>"

  let kycInfo = KYCInfo()
  kycInfo.provider = provider
  
  // Initiate FL KYC flow with kycInfo object
  ...
Copy
Copied
  val provider = Provider()
  provider.clientNumber = "<PersonId>"
  provider.name = "<ProviderName>"

  val kycInfo = KycInfo()
  kycInfo.provider = provider
  
  // Initiate FL KYC flow with kycInfo object
  ...

3. Initiate Fourthline identification flow

Now, you must initiate and display the Fourthline identification flow to the customer.

Fourthline provides two options for the identification flow depending on your integration needs:

  • "Drop-in" solution: A ready-made UI that is easy to integrate and provides a complete user experience for the customer.
  • "White-label SDK": A customizable set of modules, which you can fully design and define each part of the user experience.
note

Solaris recommends using Fourthline's "Drop-in" solution as a complete and consistent integration. However, we also support custom Fourthline integrations. This guide explains the process with the Drop-in solution.

Build the data source

Now, you must create the Fourthline "data source", which will be used to store the identification data. Use the previously retrieved information of supported identification documents to build the "data source". However, please note that the data structure received from the Solaris API can not be used directly as input for the Fourthline data source as it needs to be slightly transformed.

For instructions on how to build the "data source", check the relevant documentation:

Initiate Fourthline flow

Configure Fourthline's identification flow to collect the following information from the customer:

  • Scanned ID document (documentFlow)
  • Selfie (selfieFlow)
  • Device location data (locationFlow)

See the below examples on how to configure and initiate Fourthline's Drop-in flow to retrieve this data.

iOS/SwiftAndroid/Kotlin
Copy
Copied
var kycInfo = ... // kycInfo previously set up
var dataSource = ... // dataSource previously set up

Orca.builder
  .withCustomFlow()
  .addLocationFlow()
  .addDocumentFlow()
  .addSelfieFlow()
  .noMoreFlows()
  .addDataSource(dataSource)
  .addKycInfo(info)
  .present { completionReason in
    switch completionReason {
      case .completed(let kycInfo):
        // Process flow output
        // ...
      // ...
  }
Copy
Copied
val kycInfo: KycInfo // kycInfo previously set up
val dataSource: DataSource // dataSource previously set up

Orca.Builder(requireContext())
    .withCustomFlow()
    .addLocationFlow()
    .addDocumentFlow()
    .addSelfieFlow()
    .noMoreFlows()
    .addDataSource(dataSource)
    .present { finishReason ->
      if (finishReason is OrcaFinishReason.Completed) {
        // Process flow output
        // ...
      }
      // ...
    }

4. Fourthline flow output

After the customer has completed the identification flow, you must create a .zip file containing the collected KYC data on the customer's device and upload it to your backend.

For instructions on how to create the .zip file, check the relevant documentation:


Step 5: Upload the KYC data

After the customer completes the identification process via Fourthline, you must upload the .zip file containing the identification data to Solaris.

POST Upload zip file

This endpoint uploads a .zip file containing the identification data to the person identification specified in the request URL. The identification must have already been completed.

How to create the zip file?

If you intend to construct the Fourthline KYC data file within your system instead of relying on the provided Fourthline capabilities, please consider the following XML conventions when creating the .zip file:

  • Provider: Solaris' identifier on Fourthline.
  • ClientNumberProvider: The person ID of the customer on Solaris' system.
  • ModifiedDateTime: Always select the current date. Must not be older than 7 days.
  • DocumentNumber = Must be unique. It's not possible to successfully identify with the same document number twice.

This also applies when creating KYC data files manually during testing.

Request example

Copy
Copied
POST /v1/persons/{person_id}/identifications/{id}/zip
document=<file handle>

Response example

Copy
Copied
201 Created
{
  "id": "ec59766a28316783c6aab1004c43b640cdoc",
  "name": "RackMultipart20220518-8-12uqxum.zip",
  "content_type": "application/zip",
  "document_type": "OTHER",
  "size": 35349788,
  "customer_accessible": false,
  "created_at": "2022-05-18T15:15:27.000Z",
  "partner_accessible": true
}

Click here to view the full API reference


Step 6: Request Qualified Electronic Signature (optional)

In this step, you will initiate a QES flow to collect your customer's Qualified Electronic Signature on the relevant contracts and documents. The contracts could be a simple KYC report or contracts related to the product the customer is being identified for, such as a loan contract. Please note the following:

  • You must first show a screen to the customer to explain the QES process.
  • The customer must be able to review the documents before the QES process starts.
  • After the customer reviews the documents, they must request an SMS OTP to sign the documents.
  • The customer will receive an SMS OTP on their verified mobile number, which they must enter in your app.
  • After successful signing, you must send the signed documents to your customer via email or enable them to download the documents on your app.
attention

The step could be optional depending on the use case and the branch. However, please note that QES is mandatory for onboarding customers in Italy and France.

PATCH Start QES process

This method begins the QES process for a person identification via Fourthline. When called, it prompts Fourthline via their QES provider to send an SMS OTP to the registered mobile phone number of the customer.

note

The OTP expires after five minutes. During this five-minute window, any newly requested OTPs will not be valid. Therefore, Solaris recommends waiting five minutes before reissuing an OTP.

Request example

Copy
Copied
PATCH /v1/persons/{person_id}/identifications/{id}/authorize

Response example

The customer must enter the OTP within the validity period. The status of the identification changes to confirmation_required until you confirm the QES.

Copy
Copied
{
    "id": "a7a57dadfcc83117b5c3b72f4113be25cidt",
    "reference": null,
    "url": null,
    "status": "confirmation_required",
    "completed_at": null,
    "method": "fourthline",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "iban": null,
    "terms_and_conditions_signed_at": "2020-07-07T11:36:29.000Z",
    "authorization_expires_at": "2022-08-11T08:38:21.000Z",
    "confirmation_expires_at": "2022-08-11T08:37:23.000Z",
    "current_reference_token": "1234-5678",
    "estimated_waiting_time": null
}

Click here to view the full API reference

PATCH Confirm QES

After the customer enters the SMS OTP, use this endpoint to confirm the QES. Call this endpoint when the person identification reaches the status confirmation_required.

Request example

Copy
Copied
PATCH /v1/persons/{person_id}/identifications/{id}/confirm
{
    "token": "1234"
}

Response example

Copy
Copied
{
    "id": "a7a57dadfcc83117b5c3b72f4113be25cidt",
    "reference": null,
    "url": null,,
    "status": "confirmed",
    "completed_at": null,
    "method": "fourthline",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "iban": null,
    "terms_and_conditions_signed_at": "2020-07-07T11:36:29.000Z",
    "authorization_expires_at": "2022-08-11T08:38:21.000Z",
    "confirmation_expires_at": "2022-08-11T08:37:23.000Z",
    "current_reference_token": "1234-5678"
}

Click here to view the full API reference.


Step 7: Check the identification status and outcome

Make sure you subscribe to the webhook event IDENTIFICATION to receive notifications whenever the status of an identification changes.

You can use the following endpoint to retrieve the status of the identification:

GET Retrieve person identification

This endpoint returns a person identification.

To download any of the documents submitted during the identification process, you can use the document's unique id and download the files using the document resource endpoints.

Request example

Copy
Copied
GET /v1/persons/{person_id}/identifications/{id}

Response example (successful identification)

The following example shows a successfully completed Fourthline QES identification:

Copy
Copied
{
    "id": "a7a57dadfcc83117b5c3b72f4113be25cidt",
    "reference": null,
    "url": null,
    "status": "successful",
    "completed_at": "2022-08-11T08:29:43.000Z",
    "method": "fourthline_signing",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "address": null,
    "documents": [
        {
            "id": "a6585ea2b053a69fb705a0eb963084cfcdoc",
            "name": "a7a57dadfcc83117b5c3b72f4113be25cidt_prepared_for_signing_kyc_report.pdf",
            "content_type": "application/pdf",
            "document_type": "QES_DOCUMENT",
            "size": 88139,
            "customer_accessible": false,
            "created_at": "2022-08-11T08:25:11.000Z"
        },
        {
            "id": "4d1aa91e091e375e30e94de4ab1cf0f4cdoc",
            "name": "SIGNED_a7a57dadfcc83117b5c3b72f4113be25cidt_prepared_for_signing_kyc_report.pdf",
            "content_type": "application/pdf",
            "document_type": "SIGNED_QES_DOCUMENT",
            "size": 88139,
            "customer_accessible": false,
            "created_at": "2022-08-11T08:29:43.000Z"
        }
    ],
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null,
    "current_reference_token": null
}

Response example (failed identification)

The following example shows a failed Fourthline QES identification:

Copy
Copied
{
    "id": "7fb9659e1102d83983ce1f003bf78856cidt",
    "reference": "253029ae-a95b-493a-b420-b16d035a5126",
    "url": null,
    "status": "failed",
    "completed_at": "2022-08-30T11:28:09.000Z",
    "method": "fourthline",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "address": null,
    "failure_reason": "inconsistent_data",
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null,
    "provider_status_code": "3101"
}

Click here to view the full API reference.

Refer to the full list of Fourthline's verification status codes to understand the failure reasons and how to proceed in each case.

POST Whitelist a person identification

Fourthline has a duplication check that prevents customers from identifying several times for the same partner. This endpoint enables you to whitelist a person identification so that the customer can identify again for you. However, please note the following restrictions and use cases for this endpoint:

  • You can only use this endpoint if a person has been previously identified successfully for one of your services with Fourthline and there's a need to identify again. For example, a customer has been previously onboarded for one of your services and then terminated the business relationship and now wishes to become your customer again. In this case, you can use this endpoint to whitelist the person before a new identification can take place.
  • However, you cannot use this endpoint to whitelist a failed identification.
  • This endpoint must be called while the identification resource is in status pending or processed.

Request URL

Copy
Copied
POST /v1/persons/{person_id}/identifications/{id}/whitelist

Click here to view the full API reference.


Testing

You can simulate different outcomes of the Fourthline verification when testing on Sandbox environment. Use the following endpoint to provide a valid Fourthline verification status code as the provider_status_code in the request body. Please note that the following prerequisites before calling this endpoint:

  • You must submit a valid KYC zip file as explained in Step 5.
  • The status of Solaris identification resource must be processed.

Examples:

  • 10: Verification successful (low risk)
  • 3202: Verification failed (blurry snapshot of ID document)
  • 5100: Verification failed (ID tampering detected)

For a list of all status codes available for testing, check the appendix.

Request URL

Copy
Copied
POST /v1/persons/{person_id}/identifications/{id}/identify_with_status
{
    "provider_status_code": "10"
}

What's next?

Congratulations! You've successfully integrated Solaris' Fourthline solution.

Check the following appendices section for additional information on enums and testing data.

For an overview of other KYC methods, check the customer KYC products overview page.

Useful resources

Check the following links for additional related guides and API reference documentation:


Appendix I: Enums

Identification documents

  1. List of the accepted passports for videoIdent: here
  2. List of accepted passports for postIdent: here
  3. Search for a identification document: here

List of passports with address

The following table shows the list of documents, that has the address included in the identification document, and allows you to perform identification without the proof of address document.

Document Issuer Country Type (ID/PP)
MLT-BO-02001 Malta ID
MLT-BO-03001 Malta ID
SVK-BO-02001 Slovakia ID
SVK-BO-05001 Slovakia ID
SVK-BO-04001 Slovakia ID
ITA-BO-04003 Italy ID
ITA-BO-03004 Italy ID
ITA-BO-03002 Italy ID
ITA-BO-03001 Italy ID
ITA-BO-03003 Italy ID
DEU-BO-01003 Germany ID
DEU-BO-02001 Germany ID
SGP-BO-01001-A Singapore ID
SGP-BO-01001 Singapore ID
CZE-BO-04001 Czech Republic ID
CZE-BO-04002 Czech Republic ID
IND-AO-01001 India Passport
CHN-AO-04003 China Passport
BGR-AO-01005 Bulgaria Passport
SVN-AO-02001-02003 Slovenia Passport
SVN-AO-02004 Slovenia Passport
SVN-BO-02001 Slovenia ID
SVN-AO-01004 Slovenia Passport
POL-BO-02001-02003 Poland ID
ESP-BO-03001 Spain ID
ESP-BO-05001 Spain ID
HRV-BO-02001 Croatia ID
HRV-AO-02001 Croatia Passport
FRA-BO-02002 France ID
FRA-AO-03001-03003 France Passport
MAR-AO-02001 Morocco Passport

Identification status

The following table includes the possible values for the identification status using Fourthline and their descriptions.

Status Description
created The identification resource has been created for a customer.
pending The identification process has been initiated for the customer.
processed The KYC data has been successfully received and structurally checked.
authorization_required You must now initiate the QES process when the identification reaches this status by calling PATCH Start e-signing process to send an SMS OTP to the customer's mobile number.
confirmation_required The customer received an SMS OTP for the QES on their verified mobile number and they must enter it on your UI. After the customer enters the OTP, you must call PATCH Confirm QES e-signing process to complete the QES process.
successful The identification process was successful.
failed The identification process failed. This could be for different reasons. Check the [appendix](#appendix-ii-fourthline-status-codes for possible scenarios.
expired The identification resource expired. This happens 90 days after the last status transition if the identification isn't in a final state.

Appendix II: Fourthline status codes for testing

The following Fourthline status codes are available for testing:

Type Possible status codes
Success Risk values: 10, 20, 30
Inconsistent data 2001, 2002, 2003, 3001, 3002, 3003, 3005, 3100, 3101 3102, 3103, 3104, 3105, 3200, 3201, 3202, 3203, 3204, 3205, 3300, 3304, 3305, 3306, 3307, 3400, 3401, 3402, 3403, 3404, 3405, 3406
Unacceptable (Rejected) 4110, 4120, 4140
Unacceptable (Fraud) 5100, 5200, 5300, 5400

For a full list of all possible Fourthline verification status codes, refer to Fourthline's online documentation (password-protected).