Video identification via IDnow

This guide describes how to implement video identification via IDnow for completing the Know Your Customer (KYC) process in your solution. You can implement this feature either as a standalone solution or in combination with Solaris CRR products.

Introduction

User journey

Below are the steps involved in performing customer KYC using video identification via IDnow:

1. In your frontend, during the sign-up flow, the customer provides the required data points and their consent to Solaris' Terms and Conditions and data processing terms.
2. Inform the customer that they will be redirected to IDnow to complete the identification process. List the documents that they will be required to provide.
3. Your solution forwards the customer and their data to IDnow using the IDnow SDK.

4. IDnow will prompt the customer to begin a video identification session with an IDnow agent (either in English or in German). The customer must provide the following:

   • A government-issued identification document (e.g., passport or national ID card).
   • A document that proves their address (only if their identification document does not include an address).
   • A valid mobile number.

5. During the video session, the following steps will occur:

   • The IDnow agent will verify the data provided by the customer during your sign-up flow against the data in their identification document.
   • The IDnow agent will collect any missing information.
   • IDnow will verify the customer's mobile number using an SMS one-time password.
6. Once the process completes, the customer will be redirected to your frontend to complete the sign-up flow.

Eligibility

Video identification via IDnow is only available for customers residing in Germany. Additionally, your customer must possess one of the documents listed on IDnow's supported documents page.

If your customer does not have an identification document from the supported list, then you must complete KYC using a different method.

For more information about which KYC method fits which use case, see the KYC section of the onboarding requirements guide.

System prerequisites

Before integrating this feature, you must implement the following requirements in your solution:

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 Solaris.

• Collect the customer's consent to Solaris' 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.

IDnow integration

In addition to the Solaris technical prerequisites, you must also integrate IDnow into your solution. You can achieve this either using IDnow's mobile SDKs (available for iOS and Android) or using their webview APIs (for desktop).

For instructions on how to set up IDnow in your solution, see the following IDnow documentation links:

• Mobile:

  • iOS SDK
  • Android SDK

• Desktop (Webview):

  • API documentation

Please read the security considerations below before completing this section.

Security considerations

Video identification methods can be manipulated by identity fraudsters who collect personal data from individuals under false pretenses (e.g., app testing). Therefore, it's crucial that your solution integrates the data collection and the video identification processes. This minimizes the threat of fraudsters hijacking the customer identification session.

For security reasons, Solaris strongly recommends using the mobile SDKs for video identification instead of the webview APIs.

Webhooks

You must subscribe to the following webhook events to ensure that your system receives notifications for crucial events in the identification process. For detailed instructions on implementing Solaris webhooks, see the webhooks documentation.

• IDENTIFICATION
• PERSON_CHANGED
• PERSON_DELETED
• PERSON_MOBILE_NUMBER_CREATED
• PERSON_MOBILE_NUMBER_DELETED

Step 1: Collect customer data and create person resource

You must begin by collecting the mandatory data points from the customer in your sign-up flow, including timestamps from when the customer consented to each of the legal and compliance screens. Afterward, pass all the data points to Solaris by calling the API to create a person resource.

API reference

For a complete list of endpoints, properties, and examples related to the person resource, visit the following links:

• Person resource API reference:

  • POST Create person
  • GET Retrieve a person
  • PATCH Update person

Related webhook events

• PERSON_CHANGED
• PERSON_DELETED

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)

Request URL

POST /v1/persons

Response

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.

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

Request URL

PATCH /v1/persons/{id}

Click here to view the full API reference

Step 2: Create the identification resource for the customer

Once you have collected the customer's data, you may initiate the KYC process. First, you must create an identification resource for the customer. This resource sets various parameters for the identification process and stores the results returned by IDnow.

API reference

For a complete list of endpoints, properties, and examples related to customer identification (KYC), visit the following link:

• Customer identification (KYC) API reference

Related webhook events

• IDENTIFICATION

POST Create identification

Call this endpoint to create an identification resource for the person specified in the request URL, and add the following properties to the request body:

• method: The identification method to use. In this case, set the value to idnow.
• language: The customer's preferred language for the identification process. Possible values are EN and DE.
• proof_of_address_type: The type of document submitted by the customer as a proof of address. This field is mandatory if the customer's identification document does not include their address.
• proof_of_address_issued_at: The date when the proof of address document was issued. This field is mandatory if the customer's identification document does not include their address. It may not be older than 6 months.

Request example

POST /v1/persons/{person_id}/identifications
{
  "method": "idnow",
  "language": "DE",
  "proof_of_address_type": "GAS_BILL",
  "proof_of_address_issued_at": "2022-09-21"
}

Response example

The API call will return an identification object with a unique id (i.e., identification_id) and an initial status of created.

{
    "id": "6dc54352d6793a892e0702850d07b831cidt",
    "reference": null,
    "url": null,
    "status": "created",
    "completed_at": null,
    "method": "idnow",
    "proof_of_address_type": "GAS_BILL",
    "proof_of_address_issued_at": "2022-09-21",
    "language": "DE",
    "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

The purpose of this endpoint is to provide you with a list of supported identification documents per issuing country. You can use this endpoint to inform your customers of the required documents before starting the identification process.

The API call returns an array of document types with the corresponding issuing countries listed as ISO country codes (ISO-3166-1 alpha 2). If a customer provides a document type that is not supported, their identification process will fail.

Request URL

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

Click here to view the full API reference

PATCH Request person identification

Call this endpoint to trigger the identification flow with IDnow for the specific customer.

Request URL

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

Response example

The API call returns the identification object with the status pending. The status will remain pending until the customer completes the identification. Additionally, the payload includes the following key properties:

• url The URL to which you must redirect the customer to complete the identification. Valid for 14 days.
• reference: An internal IDnow identification token for the session (format: ABCDEFGH). Do not share this with the customer under any circumstances.

{
    "id": "6dc54352d6793a892e0702850d07b831cidt",
    "reference": "TST-KCCEY",
    "url": "https://go.test.idnow.de/solarisbankvideoidentsandbox/identifications/6dc54352d6793a892e0702850d07b831cidt",
    "status": "pending",
    "completed_at": null,
    "method": "idnow",
    "proof_of_address_type": "GAS_BILL",
    "proof_of_address_issued_at": "2022-09-21",
    "language": "DE",
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null,
    "estimated_waiting_time": 60
}

Click here to view the full API reference.

IDnow video identification session

Your customer will now be redirected to an IDnow-branded landing page, where they consent to IDnow's Terms & Conditions and confirm that they have a valid ID document for the video identification. They must also provide a valid mobile number, which the IDnow agent will verify during the call using an SMS OTP.

Customers may choose to conduct the call with a German- or English-speaking IDnow agent. When the video identification call begins, the agent will greet the customer on behalf of either you or Solaris (depending on your agreement with Solaris). The agent will then verify the customer's mobile number, first name, and last name. If there are any missing data properties, the agent will provide these as well, and they will be added to the customer's person resource.

GET Retrieve person identification

Once the identification completes successfully, call this endpoint to retrieve the finalized person identification. If you use the include_documents filter, the API will also return the documents submitted by the customer during the process. To download any of these documents, use the document's unique id to call the document download endpoints.

Request URL

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

Click here to view the full API reference.

Other identification endpoints

• GET Index identifications for a person
• POST Upload documents for a person identification
• GET List the IDnow attempts of a person identification
• GET List IDnow legitimation data.

After the customer successfully complete the video identification process, you can download the documents submitted during the identification session using our document-related endpoints here.

Testing

IDnow offers test scenarios to simulate different outcomes for the identification process. To trigger a test scenario, you can create a person resource and set the first_name or last_name to one of the following prefixes and the name of the relevant test case. The format is as follows:

{{Test scenario}}-{{Test case}}

Example:

X-MANUALTEST-HAPPYPATH

Test scenarios

The available test scenarios are as follows:

Happy path test tutorial

Complete the following steps to simulate a successful identification workflow with IDnow on Sandbox.

1. Create a person

Create a person resource using the following endpoint and set the value of the first_name field to X-MANUALTEST-HAPPYPATHto trigger the HAPPYPATH scenario and any value for the last_name in the request body.

Request

POST /v1/persons
{
   "first_name": "X-MANUALTEST-HAPPYPATH",
   "last_name": "{{random_name}}"
}

2. Create an identification resource

Create an identification resource and specify the identification method as idnow in the request body of the following endpoint. Add the person_id returned from the previous API call to the request URL.

Request example

POST /v1/persons/{person_id}/identifications
{
   "method": "idnow"
}

3. Trigger the identification

To trigger the identification flow, call the following endpoint, using the person_id and the identification id returned from the previous API call in the request URL.

Request example

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

Response example

The API call will return the details of a test video identification session, including url (for web browser) and reference (for mobile app).

{
    "id": "b80ea8c7f76909749763e77f3efc2c87cidt",
    "reference": "TST-CHMUV",
    "url": "https://go.test.idnow.de/solarisbankvideoidentsandbox/identifications/b80ea8c7f76909749763e77f3efc2c87cidt",
    "status": "pending",
    "completed_at": null,
    "method": "idnow",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "language": null,
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null,
    "estimated_waiting_time": 60
}

4. Complete the identification flow

Depending on whether you want to test the identification on the web browser or IDnow mobile application, you can click on the URl to go to the web browser session or enter the reference in the mobile app.

Afterwards, you'll be directed to the video identification flow where you have to:

1. Enter any mobile number that starts with 0 or you can use the static value: +15550101, check all boxes and click on Start identification.
   
2. The flow will start and you'll start seeing different pop-ups with instructions, simulating what would happen in a real video identification session.
3. The flow goes to the successful stage and you have to confirm the identification by entering the following static Ident code: 123456.
   
4. The successful identification screen will appear.
   
5. Afterward, you can call the following endpoint, which will show the identification status as successful. Additionally, the webhook event IDENTIFICATION will be triggered as well after a successful identification.

Request URL:

GET /v1/persons/{person_id}/identifications

What's next?

Congratulations! You have successfully completed the customer KYC process using IDnow video identification.

Check the following appendices for more information on enum values and testing data.

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

Useful resources

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

• Customer identification (KYC) API reference
• Person Documents API reference

Appendix I: Enums

Document types

The following table includes the possible values for the field document_type and their descriptions.

IDow status values

The following table includes the possible values for the field status for the video identification process carried out by IDnow and the related description of each status.

IDnow provides a reason whenever the identification has a canceled or aborted status. No reason can be disclosed for the final failed status.

IDnow failure codes

The following table describes the possible failure or cancellation reasons for IDnow video identification.

Identification documents

1. List of accepted passports for video identification via IDnow: here
2. List of accepted passports for postIdent: here
3. Search for an identification document: here

List of passports with address

The following table lists all ID types that include the bearer's address, which you can use to perform identification without having to provide a proof of address document.

Appendix II: IDnow status transitions

Only the following transitions can occur during an IDnow identification session:

Case 1: Happy path

created → pending → successful

Case 2: Suspicion of fraudulent behavior by IDnow that was not confirmed. Identification was marked as successful after review.

created → pending → canceled → successful

Case 3: Fraudulent behavior was detected during a review of an identification that was previously marked as successful.

created → pending → successful → canceled