Bankident webview

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

This section includes step-by-step instructions on how to integrate Bankident webview.

Product overview

Solaris' standalone Bankident webview enables you to identify customers in a unified session. You initiate the session, and Solaris handles the intermediate identification steps, ensuring rapid integration and low maintenance.

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.

• IDENTIFICATION_SESSION
• PERSON_CHANGED
• PERSON_DELETED
• PERSON_MOBILE_NUMBER_CREATED
• PERSON_MOBILE_NUMBER_DELETED

Integration flow

Integration steps

Integrate Solaris' Bankident webview by completing the following steps:

Setup

1. Collect the mandatory information and consent to the legal and regulatory requirements from the customer in your sign-up flow.
2. Create a person resource for your customer using POST Create person.
3. Create the customer's mobile number.

Identification session creation

1. Trigger the identification process by creating an identification session using POST Create person identification session.
2. Redirect the customer to the URL returned from the previous call to complete the identification process.

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

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.

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 (Use ISO 3166-1 alpha-2 codes)
• mobile_number
• address (Street, Number, City, Post Code, Country, State)
• data_terms_signed_at (UTC timestamp)
• terms_conditions_signed_at (UTC timestamp)

Request URL

POST /v1/persons

Request example

{
  "salutation": "Mr",
  "first_name": "Marc",
  "last_name": "O'Polo",
  "birth_date": "1999-01-01",
  "nationality": "DE",
  "mobile_number": "+4917612345678",
  "address": {
    "line_1": "Solaris street",
    "line_2": "1",
    "postal_code": "10119",
    "city": "Berlin",
    "country": "DE"
  },
  "tax_information": {
    "tax_assessment_country": "DE"
  },
  "terms_conditions_signed_at": "2021-01-01T00:00:00Z",
  "data_terms_signed_at": "2021-01-01T00:00:00Z"
}

Response

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

{
  "id": "dc1a6812a14f6cc338cd084208535bcdcper",
  "salutation": "Mr",
  "first_name": "Marc",
  "last_name": "O'Polo",
  "birth_date": "1999-01-01",
  "nationality": "DE",
  "mobile_number": "+4917612345678",
  ...
}

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}

Request example

{
  "email": "new.email@example.com",
  "address": {
    "line_1": "New Street",
    "line_2": "1",
    "postal_code": "10119",
    "city": "Berlin",
    "country": "DE"
  }
}

• API Reference: Update person

Step 2: Create mobile number

In this step, you must attach a mobile number to the person resource.

POST Create mobile number

Request URL

POST /v1/persons/{person_id}/mobile_number

Request example

{
  "number": "+15550101"
}

Response example

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

Click here to view the full API reference.

For more information about how to manage mobile numbers (e.g., changing or deleting a number), check the related mobile number management guide.

Step 3: Create person identification session

In this step, you must create an identification session for the customer to start the identification process. The identification session is a series of screens containing all the intermediate identification steps your customer must complete in a single identification webview session.

(Optional) POST Check identification eligibility

As an initial verification step, you can check whether the relevant customer is eligible for the given identification method or not based on their data, such as nationality, place of residence, or identification document.

This endpoint validates whether the person specified in the request URL is eligible to complete a given identification method. You must add the identification method for which you want to check the customer's eligibility in the request body.

Request example

POST /v1/persons/{person_id}/identification_eligibility_checks
{
  "method": "bank"
}

Response example

The API call returns a response as to whether the person is eligible for identifying with a particular method or not. In case of failure, a reason is provided in the field failure_reason.

{
    "method": "bank",
    "eligible": true,
    "failure_reason": "null"
}

Click here to view the full API reference

(Optional) POST Validate IBAN

Solaris offers an endpoint for validating the IBAN supplied by the customer. If the IBAN is valid, then the API will return information about the account's associated bank.

Request URL

POST /v1/iban_lookups

Click here to view the full API reference.

POST Create person identification session

This endpoint creates an identification session for the person specified in the request URL. You must include a callback_url for the end of the flow and set the identification_methods to be used for the identification.

Request example

POST /v1/persons/:person_id/identification_sessions
{
    "callback_url": "https://www.callbackurl.com",
    "identification_methods": [
        "bank"
    ]
}

Response example

The API call returns an object for the identification session with a unique id and the url to which you must redirect the customer to complete the identification process.

Additionally, the API response includes the status of the identification session. For a list of possible values for this field, check the appendix.

{
    "callback_url": "https://www.callbackurl.com",
    "status": "created",
    "id": "acdede097f821bd8037465d691f69506ises",
    "url": "https://person-onboarding.solaris-staging.de/9AXlUH0ptsZoFef2n8LKiqpEAizdJTjVQ4tzZeu1LpvqbK201REXFG_EBwiGTw0PLlHWCaA7NLOOcUh1u_a7HUpp7wYMNlGnzALka-v_9MVOxOIfN73lFjFg7JMtBdJO",
    "identification_methods": [
        "bank"
    ]
}

Click here to view the full API reference

GET Retrieve person identification session

This endpoint returns the information about the identification session created for a person. Register to the webhook event IDENTIFICATION_SESSION for status updates on the identification session.

Request example

GET /v1/persons/{person_id}/identification_sessions/{session_id}

Response example

200 Ok
{
    "callback_url": "https://www.callbackurl.com",
    "status": "created",
    "id": "acdede097f821bd8037465d691f69506ises",
    "url": "https://person-onboarding.solaris-staging.de/9AXlUH0ptsZoFef2n8LKiqpEAizdJTjVQ4tzZeu1LpvqbK201REXFG_EBwiGTw0PLlHWCaA7NLOOcUh1u_a7HUpp7wYMNlGnzALka-v_9MVOxOIfN73lFjFg7JMtBdJO",
    "identification_methods": [
        "bank"
    ]
}

Click here to view the full API reference

Webview session screens

This section includes information and descriptions about the different screens your customer will interact with to complete the identification process.

Introduction screen

This is the first screen the user interacts with after the URL redirect from your service. It provides context and prepares the customer for the next steps ahead.

Verify mobile number screens

The Bankident KYC session requires a verified mobile number to send OTP SMS for confirmations to the user. Solaris sends an SMS OTP to the customer's mobile number, and the customer must input this OTP into this screen to verify the number.

Customer input on this screen:

• SMS OTP to verify their mobile number

Verify bank account with cent transfer

Within the following screens, Solaris validates the customer's provided IBAN and verifies the bank account ownership with a cent transfer.

Screen 1: IBAN validation

On this screen, the customer is prompted to enter their IBAN. Then Solaris runs identity checks through SCHUFA to verify if the customer has been identified before with the provided IBAN.

Customer input on this screen:

• IBAN

Screen 2: Bank account login

The customer is prompted to log into their bank account to trigger the payment initiation in this screen. Through this step, Solaris verifies the account ownership.

Customer input on this screen:

• User ID
• Password

Screen 3: Confirm transaction

In this screen, the customer verifies that they have access to their account by confirming the cent transfer with the bank's 2FA method.

Customer input on this screen:

• SMS OTP

Confirm with Qualified Electronic Signature (QES)

After a successful payment transfer, the customer can proceed with signing the relevant contracts.

Screen 1: Contract signature

On this screen, the customer should be able to review and read the contracts that must be signed before the QES process starts.

Customer input on this screen:

• Download contract

Screen 2: Contract confirmation

In the following screens, the customer signs the relevant documents by entering an SMS OTP received on their verified mobile number.

Customer input on this screen:

• SMS OTP

Screen 3: Successful completion

The customers successfully signed the contract(s)

What's next?

Congratulations! You've successfully integrated Solaris' Bankident webview solution.

Check the following appendix section for additional information on enums, testing data, and Bankident FAQs.

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:

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

Appendix I: Enums

Identification session status

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

Appendix II: Testing data

Your solution must consider the following edge cases for Bankident:

• The user data was not found.
• The user's IBAN could not be matched to the provided name.
• The account provided is a JOINT account (i.e., shared account).
• An authorized person on the account (i.e., someone who does not own the account) attempts to identify.
• Timeout of 10 minutes between payment initiation and finalization of QES.

You can test edge cases with the following mocked IBANs on Sandbox:

Appendix III: Bankident rejection reasons and error codes

The following table includes the possible failure reasons for Bankident. These failure reasons are also relevant for the Bankident+ method.

Appendix IV: Bankident FAQs

The following are common questions and answers related to the integration process of Bankident solution. If you have other questions or use cases not mentioned in this guide, contact your Partner Manager for support.

General

How many identification attempts can a user make?

A single person resource can make a maximum of 20 attempts before receiving a generic error message.

Can I reuse a successful identification for different companies?

There are no technical restrictions on reusing an identification. However, you must define GDPR measures regarding data cleanup and consent reuse.

Eligibility & Data

Are non-German IBANs supported?

No. Bankident currently supports only German IBANs. If your customer does not have a German IBAN, consider using VideoIdent or Fourthline.

Which mobile country codes are supported?

Solaris supports all mobile country codes except:

• Iran (+98)
• North Korea (+850)

Are international addresses supported?

Yes, addresses from any country are accepted. However, identification success rates are significantly lower for addresses outside Germany. SCHUFA primarily stores data for German residents, so matching an international address is less likely to succeed.

Timeouts & Validity

How long is the SMS token valid?

The SMS OTP for the Qualified Electronic Signature (QES) process is valid for 10 minutes.

What is the timeout for the bank connection widget?

The session times out 10 minutes after the customer initiates the payment. The timer tracks the window between the payment (cent transfer) and the final signature; it does not include the time spent on data entry.