# Bankident webview This section includes step-by-step instructions on how to integrate Bankident webview. ## Product overview Solaris' standalone Bankident identification session in webview enables you to quickly identify your customer in a unified identification session. You only need to start an identification session, whereas Solaris handles the intermediate identification steps, allowing rapid integration and low maintenance efforts. If you want to use IDnow 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-3-create-person-identification-session). ## 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](/api-reference/webhooks/). - [IDENTIFICATION_SESSION](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/identification_session/post) - [PERSON_CHANGED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_changed/post) - [PERSON_DELETED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_deleted/post) - [PERSON_MOBILE_NUMBER_CREATED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_mobile_number_created/post) - [PERSON_MOBILE_NUMBER_DELETED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_mobile_number_deleted/post) ## 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](#post-create-person). 3. Create and verify the customer's mobile number. **Identification session creation** 1. Trigger the identification process by creating an identification session using [POST Create person identification session](#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. **API reference** For a complete list of endpoints, properties, and examples related to the `person` resource, visit the following links: - [Person resource API reference](/api-reference/onboarding/persons/#tag/Persons): - [POST Create person](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons/post) - [GET Retrieve a person](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons~1%7Bid%7D/get) - [PATCH Update person](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons~1%7Bid%7D/patch) **Related webhook events** - [PERSON_CHANGED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_changed/post) - [PERSON_DELETED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_deleted/post) :::info Important points about data collection - Please consider the special requirements for data collection highlighted in the [onboarding requirements guide](/guides/get-started/onboarding-requirements/2-data-collection/#important-considerations-for-data-collection). - You must submit the information exactly as it appears in official documents. - When testing the process on Sandbox, please ensure that each person you create has unique values for `first_name`, `last_name`, `birth_city`, and `birth_date`. If you create over 1000 identical person resources, the API will return a `400` error. - Don't use any personal data when testing this endpoint on Sandbox. ::: #### 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) - `address` (Street, Number, City, Post Code, Country, State) - `mobile_number` - `data_terms_signed_at` (UTC timestamp) - `terms_conditions_signed_at` (UTC timestamp) **Request URL** ```json 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](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons/post) #### 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 apply one of the following options to 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`. - Solaris recommends collecting the `nace_code` from the customer for the sake of data quality. ::: **Request URL** ```shell PATCH /v1/persons/{id} ``` [Click here to view the full API reference](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons~1%7Bid%7D/patch) ## 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 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. - [Mobile number resource API reference](/api-reference/onboarding/persons/#tag/Person-mobile-numbers) **Related webhook events** - [PERSON_MOBILE_NUMBER_CREATED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_mobile_number_created/post) - [PERSON_MOBILE_NUMBER_DELETED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_mobile_number_deleted/post) :::note 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:** ```json 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. ```json { "id": "91e4d939d781b8eb30d1ee86809761c2cmno", "number": "+15550101", "verified": false } ``` [Click here to view the full API reference.](/api-reference/onboarding/persons/#tag/Person-mobile-numbers/paths/~1v1~1persons~1%7Bperson_id%7D~1mobile_number/post) #### 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:** ```json POST /v1/persons/{person_id}/mobile_number/authorize { "number": "+15550101" } ``` **Response example:** ```json { "id": "91e4d939d781b8eb30d1ee86809761c2cmno", "number": "+15550101", "verified": false } ``` [Click here to view the full API reference.](/api-reference/onboarding/persons/#tag/Person-mobile-numbers/paths/~1v1~1persons~1%7Bperson_id%7D~1mobile_number~1authorize/post). #### 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:** ```json POST /v1/persons/{person_id}/mobile_number/confirm { "number": "+15550101", "token": "212212" } ``` **Response example:** ```json { "id": "91e4d939d781b8eb30d1ee86809761c2cmno", "number": "+15550101", "verified": true } ``` [Click here to view the full API reference.](/api-reference/onboarding/persons/#tag/Person-mobile-numbers/paths/~1v1~1persons~1%7Bperson_id%7D~1mobile_number~1confirm/post) ### Mobile number management For more information about how to manage mobile numbers, check the related [guide](/guides/digital-banking/mobile-number-management). Verifying the mobile number is done within the webview session. ## 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** ```json 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`. ```json { "method": "bank", "eligible": true, "failure_reason": "null" } ``` [Click here to view the full API reference](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identification_eligibility_checks/post) ### (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** ```shell POST /v1/iban_lookups ``` [Click here to view the full API reference.](/api-reference/digital-banking/account-management/#tag/IBAN-validation) ### 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. Make sure to add a URL with the proper format with HTTPS://. Otherwise, a session error may occur. **Request example** ```json 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](#identification-session-status). ```json { "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](/api-reference/identity/identifications/#tag/Identification-sessions/paths/~1v1~1persons~1%7Bperson_id%7D~1identification_sessions/post) ### 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** ```shell GET /v1/persons/{person_id}/identification_sessions/{session_id} ``` **Response example** ```json 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](/api-reference/identity/identifications/#tag/Identification-sessions/paths/~1v1~1persons~1%7Bperson_id%7D~1identification_sessions~1%7Bidentification_session_id%7D/get) ## 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. ![Bankident webview: Introduction screen](/assets/websession_screen_intro.9751612ff7430d5e0461e6ee910cf990f32043c8e7389d9d988b2b7cc550378d.b242e30b.png) ### 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 ![Bankident webview: Mobile number verification screen](../assets/websession_screen_mobile verification.png) ![Bankident webview: Successful mobile number verification screen](../assets/websession_screen_mobile verification_success.png) ### 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 ![Bankident webview: IBAN validation screen 1](/assets/websession_screen_iban_validation.3955a2ec81acb94e6e99591a4dd4a92e324731d816dc0076156a824915188ab2.b242e30b.png) ![Bankident webview: IBAN validation screen 2](/assets/websession_screen_iban_validation2.afd741db6df0a5f4effbde7ddac7e2f0c0248c9156b9b8b60ce7cf6e2fdfe8d5.b242e30b.png) #### 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 ![Bankident webview: Bank account login screen 1](/assets/websession_screen_bank_login.7dea4da414cf64b112773c67fa993d29e25a8395d66d02361fe5019fcc805ef2.b242e30b.png) ![Bankident webview: Bank account login screen 2](/assets/websession_screen_bank_login2.e9609be604ca2c71af9b7830e92418fc35b00e5994aebc2e428ee16b95aca62a.b242e30b.png) #### 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. The bank 2FA method could be entering an SMS OTP or confirming an in-app push notification. **Customer input on this screen:** - SMS OTP ![Bankident webview: Transaction confirmation screen](/assets/websession_screen_cent_transfer.494f69261314ba080281b2aa97e303b4fb0b9740b97e367189fdc105e238b49c.b242e30b.png) ![Bankident webview: Successful payment transfer screen](/assets/websession_screen_bank_login3.2f515d32a311285383036072d079e1c14a25214ebef6f6862f033e36139a7f17.b242e30b.png) ### Confirm with Qualified Electronic Signature (QES) After a successful payment transfer, the customer can proceed with signing the relevant contracts. 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. #### 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 ![Bankident webview: Contracts review screen](/assets/websession_screen_qes_signature1.adb7778cbcaf07fe772b67ceeca44782057e9c8103134ae3372121909295d814.b242e30b.png) #### 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. not **Customer input on this screen:** - SMS OTP ![Bankident webview: QES confirmation screen 1](/assets/websession_screen_qes_confirmation2.59851f030828a631adf6f7b22cf67cdc350811481c4d154090131f4d461ccba5.b242e30b.png) ![Bankident webview: QES confirmation screen 2](/assets/websession_screen_qes_confirmation2.1.35195bfb5aa26919a68a0f07e9d8969381187812f4cb84bfc37167a42af5cc5b.b242e30b.png) ![Bankident webview: QES confirmation screen 3](/assets/websession_screen_qes_confirmation2.2.4397a086a567851e274418e9c5f811c94e50f308724a94c162392c68b27f543d.b242e30b.png) #### Screen 3: Successful completion The customers successfully signed the contract(s) ![Bankident webview: Successful QES screen](/assets/websession_screen_qes_success3.d4762768ce1a20e5b38f8add4cdc33c3b09810cbd4b11f727454908961ab19ee.b242e30b.png) ## 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](/guides/kyc/) page. ### Useful resources Check the following links for additional related guides and API reference documentation: - [Customer identification (KYC) API reference](/api-reference/onboarding/persons/#tag/Persons) - [Person Documents API reference](/api-reference/onboarding/persons/#tag/Person-documents) ## Appendix I: Enums ### Identification session status The following table includes the possible values for identification session `status` and their descriptions. | Status | Description | | --- | --- | | `created` | The identification session has been created for a customer. The status remains `created` until the customer completes the identification process. | | `successful` | The customer has completed the identification process successfully. | | `expired` | The identification session has expired. This is because the customer did not complete the process within the session's validity time frame. | ## Appendix II: Testing data ### Test scenarios 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: | IBAN | Mocked behavior | Error code | | --- | --- | --- | | DE11110101010100000020 | Success from service provider & Swisscom | | | DE43110101010000000010 | Success—Access by authorized holder | | | DE22110101010100000016 | User data not found in service provider DB | HTTP 412, `MATCH_FOR_PERSON_DATA_NOT_FOUND` | | DE33110101010100000012 | User without QBit | HTTP 412, `PREVIOUS_IDENT_NOT_FOUND` | | DE44110101010100000008 | Account check failed on Schufa | HTTP 412, `PERSON_ACCOUNT_MATCH_NOT_FOUND` | | DE55110101010100000004 | Account was JOINT | HTTP 409, expectation_mismatch | | DE66110101010100000000 | Account snapshot failed | HTTP 409, expectation_mismatch | | DE77110101010100000093 | Success from service provider and unsuccessful in Swisscom | | | DE77110101010100000093 | Every subsequent Authorize QES SMS TAN will invalidate the previous TAN | | ### Happy path test scenario Complete the following steps to simulate a successful identification workflow with Bankident on Sandbox. #### 1. Create a person Create a `person` [resource](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons/post) using the following endpoint and add the following fields in the request body. **Request** ```json POST /v1/persons { "salutation": "MR", "first_name": "Leander", "last_name": "Zierfisch", "address": { "line_1": "BERLINER STR. 45", "line_2": "", "postal_code": "14169", "city": "Berlin", "country": "DE" }, "birth_date": "1978-07-15", "birth_city": "Aachen", "birth_country": "DE", "nationality": "DE", "email": "person@example.com", "employment_status": "EMPLOYED", "fatca_relevant": "false", "fatca_crs_confirmed_at": "2019-01-01T00:00:00Z", "terms_conditions_signed_at": "2019-01-01T00:00:00Z", "own_economic_interest_signed_at": "2019-01-01T00:00:00Z" } ``` #### 2. Create and verify a mobile number You can follow the same steps mentioned in the guide and use the static values. #### 3. Create an identification Create an identification [resource](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications/post) and specify the identification `method` as `bank` in the request body of the following endpoint. Add the `person_id` returned from the previous API call to the request URL. Additionally, include the `iban` for a successful identification **Request example** ```json POST /v1/persons/{person_id}/identifications { "method": "bank", "iban": "DE11110101010100000020", "terms_and_conditions_signed_at": "2020-07-07T11:36:29.000Z" } ``` #### 4. Trigger the identification To trigger the identification flow, call the following endpoint and add the `person_id` and the identification `id` returned from the previous API calls to the request URL. **Request example** ```json PATCH /v1/persons/{person_id}/identifications/{id}/request ``` **Response** ```json { "id": "a7a57dadfcc83117b5c3b72f4113be25cidt", "reference": null, "url": "https://fts-payment-initiation-wizard.solaris-sandbox.de/index.html?wizard_session_key=bfo5r16AMLlt6ZEX9Oh3JUWIkTelorupBwzIlJRR&interface_id=da05", "status": "pending", "completed_at": null, "method": "bank", "proof_of_address_type": null, "proof_of_address_issued_at": null, "iban": "DE11110101010100000020", "terms_and_conditions_signed_at": "2020-07-07T11:36:29.000Z", "authorization_expires_at": null, "confirmation_expires_at": null, "estimated_waiting_time": null } ``` #### 5. Complete the payment transfer step Go to the URL returned in the previous call and enter any number for the account number and the banking PIN and click `NEXT`. This screen simulates a login screen, in which the customer must log into their online banking and authorize a 5-cent transfer to validate the account ownership. ![Bank login screen](/assets/bankident-happypath1.abdffe12aaa36059c6631caf472230b50606467c79984e8a62f74e1a2618391e.86e4b84a.png) After clicking `NEXT`, another screen will pop up and you have to enter any TAN number to authorize the transaction. This screen simulates the screen in which the customer must enter the SMS OTP they received on their verified mobile number to authorize the transaction. ![SMS TAN screen](/assets/bankident-happypath2.16b2c6523c7a98b9f988558569c82323d395c71450cdb5934e46e92f39c5c7f6.86e4b84a.png) #### 6. Complete the QES step After successful payment transfer, complete the QES process by doing the following steps: 1. Call [PATCH Start e-signing process](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1authorize/patch). Add the `person_id` and identification `id` in the request URL. **Request** ```shell PATCH /v1/persons/{person_id}/identifications/{id}/authorize ``` **Response** ```json { "id": "a7a57dadfcc83117b5c3b72f4113be25cidt", "reference": null, "url": "https://fts-payment-initiation-wizard.solaris-sandbox.de/index.html?wizard_session_key=bfo5r16AMLlt6ZEX9Oh3JUWIkTelorupBwzIlJRR&interface_id=da05", "status": "confirmation_required", "completed_at": null, "method": "bank", "proof_of_address_type": null, "proof_of_address_issued_at": null, "iban": "DE11110101010100000020", "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 } ``` 1. Call [PATCH Confirm e-signing process](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1confirm/patch). Add the `person_id` and identification `id` in the request URL. **Request** ```shell PATCH /v1/persons/{person_id}/identifications/{id}/confirm ``` **Response** ```json { "id": "a7a57dadfcc83117b5c3b72f4113be25cidt", "reference": null, "url": "https://fts-payment-initiation-wizard.solaris-sandbox.de/index.html?wizard_session_key=bfo5r16AMLlt6ZEX9Oh3JUWIkTelorupBwzIlJRR&interface_id=da05", "status": "confirmed", "completed_at": null, "method": "bank", "proof_of_address_type": null, "proof_of_address_issued_at": null, "iban": "DE11110101010100000020", "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" } ``` 1. Afterward, call [GET Retrieve a person identification](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D/get) and the response should include a `successful` status and the signed documents with their IDs. **Request** ```shell GET /v1/persons/{person_id}/identifications/{id} ``` **Response** ```json { "id": "a7a57dadfcc83117b5c3b72f4113be25cidt", "reference": null, "url": "https://fts-payment-initiation-wizard.solaris-sandbox.de/index.html?wizard_session_key=bfo5r16AMLlt6ZEX9Oh3JUWIkTelorupBwzIlJRR&interface_id=da05", "status": "successful", "completed_at": "2022-08-11T08:29:43.000Z", "method": "bank", "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": "DE11110101010100000020", "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" } ``` ## 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 Bankident+ method. | HTTP status | Error code | Description | UI user error message | Actions | | --- | --- | --- | --- | --- | | 412 | `IBAN_USAGE_LIMIT_EXCEEDED` | The provided IBAN has been blacklisted due to reaching the limit of failed attempts for this IBAN. | DE:Sie haben das Limit an Versuchen erreicht.Bitte fahren sie mit der Video-Identifizierung fort.EN:You have reached the limit of attempts.Please continue with the video identification. | Potential Fraud attempt, onboarding should stop. Show generic message to the customer | | 412 | `MOBILE_NUMBER_NOT_VERIFIED` | The customer does not have a verified mobile number. | | Verify the mobile number and retry the call. | | 412 | `IDENTIFICATION_ATTEMPTS_EXCEEDED` | The mobile number or the combination of `first_name` and `last_name ` reached the limit of failed attempts to create an identification. | DE:Diese Identifikations-methode steht nicht zur Verfügung.Bitte fahren sie mit der Video-Identifizierung fort.EN:This identification method is not available.Please continue with video identification. | Potential Fraud attempt, onboarding should stop. Show generic message to user | | 422 | `ALREADY_IDENTIFIED_SUCCESSFULLY` | The customer has been successfully identified. | DE:Sie haben sich bereits erfolgreich identifizert.EN:You have already successfully identified yourself. | Stop onboarding. Ask customer to use their existing account. | | 412 | `MATCH_FOR_PERSON_DATA_NOT_FOUND` | The customer's record could not be found in SCHUFA. Usually happens to customers who, for example, recently moved to Germany. | DE:Diese Identifikations-methode steht nicht zur Verfügung.Bitte fahren sie mit der Video-Identifizierung fort.EN:This identification method is not available.Please continue with video identification. | No action needed | | 412 | `PERSON_ACCOUNT_MATCH_NOT_FOUND` | We could not establish a connection between the customer and the provided IBAN. The customer can try again with a different IBAN. | DE:Für diese IBAN steht diese Identifikationsmethode nicht zur Verfügung. Bitte versuchen Sie es mit einer anderen IBAN oder fahren Sie mit Video-Identifizierung fort.EN:This identification method is not available for this IBAN. Please try another IBAN or continue with video identification. | No action needed | | 412 | `PREVIOUS_IDENT_NOT_FOUND` | The customer did not meet the identification preconditions. | DE:Diese Identifikations-methode steht nicht zur Verfügung.Bitte fahren sie mit der Video-Identifizierung fort.EN:This identification method is not available.Please continue with video identification. | The customer cannot be onboarded with this identification method. | | 412 | `PERSON_MISSING_REQUIRED_DATA` | The customer is missing some of the required data.Der Person fehlen notwendige Daten | DE:Ein Fehler ist aufgetreten. Bitte kontaktieren Sie den Support.EN:An error has occurred. Please contact Solaris support. | Ask the customer to enter the missing data and retry the call. | | 412 | `DEPENDENCY_ERROR` | External provider service failure | DE:Ein Fehler ist aufgetreten. Bitte kontaktieren Sie den Support.EN:An error has occurred. Please contact Solaris support. | Contact Solaris. | | 412 | `INVALID_MODEL` | Something went wrong, tech bug. | DE:Ein Fehler ist aufgetreten. Bitte kontaktieren Sie den Support.EN:An error has occurred. Please contact the support. | Check the request JSON body and retry the call. Contact Solaris if the issue is not solved. | | 412 | `INTERNAL_REQUEST_ERROR` | Something went wrong, tech bug | DE:Ein Fehler ist aufgetreten. Bitte kontaktieren Sie den Support.EN:An error has occurred. Please contact Solaris support. | Contact Solaris. | | 412 | GENERIC_ERROR | Something went wrong, tech bug. | DE:Ein Fehler ist aufgetreten. Bitte kontaktieren Sie den Support.EN:An error has occurred. Please contact Solaris support. | Contact Solaris. | | 412 | `ACCESS_BY_ATHORIZED_HOLDER` | The customer is not the account holder of the account, but an authorized person on the account. This is not allowed for fraud protection reasons. | DE:Sie sind nicht Kontoinhaber. Bitte nutzen sie eine andere IBAN oder fahren Sie mit der Video-Identifizierung fort.EN:You are not the account holder. Please use another IBAN or continue with the video identification. | The customer can try again with a bank account of which he is the account holder. | | 412 | `EXPIRED` | The identification has expired (happens after 30 days). | DE:Ihr Identifizierungsprozess ist abgelaufen. Bitte versuchen Sie es erneut.EN:Your Identification attempt has expired. Please Try again. | A new identification must be created for the customer to restart the process. | | 412 | `ACCOUNT_SNAPSHOT_FAILED` | The payment initiation (5 cent transfer) process failed. This process step is done by an external provider and failure could have various reasons. | DE:Die Bankanmeldung oder Überweisung ist fehlgeschlagen. Bitte versuchen Sie es erneut.EN:The bank login or transfer has failed. Please try again. | The customer can try again process with a different IBAN. | | 412 | `JOINT_ACCOUNT` | The provided account for the identification is a joint account. This is not allowed for fraud protection reasons. | DE: Gemeinschaftskonten sind nicht unterstützt. Bitte nutzen sie eine andere IBAN oder fahren Sie mit der Video-Identifizierung fort.EN:Joint accounts are not supported. Please use a different IBAN or continue with video identification. | The account that was used for the identification is a joint account, please make sure to connect an account solely owned by you. | | 412 | `ACCOUNT_SNAPSHOT_EXPIRED` | The payment initiation expired. After requesting the identification (i.e. starting the payment initiation), the user has 10 minutes to complete the 5 cent transfer. Afterward, the payment initiation is expired by our service provider. | DE:Die Anmeldesitzung der Bank ist abgelaufen. Bitte versuchen Sie es erneut.EN:The bank login session has expired. Please try again. | It looks like you did not confirm the 5-cent transfer within the dedicated 10 minutes time frame. Please try to onboard again | ## 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. > How many attempts with different IBANs can one "person" submit leading to receiving generic error messages on the identification creation? 20 attempts. > Does the user have to provide a DE IBAN or can it also be an IBAN with a different country code? Currently, only **German** IBANs are supported for Bankident. If your customer doesn't have a German IBAN, check the other available identification methods [here](/guides/kyc/). > Can the user get their mobile phone number identified using every country code? Or does it have to be +49 for germany? Do you have a list of country codes allowed? All country codes are supported except for Iran and North Korea. > Can the user have an address outside of Germany? If yes, which countries are allowed? Yes, the user can have any kind of address. However, the probability that SCHUFA will correctly identify the person will decrease, since SCHUFA checks depend on the person's registered address. > How long is an SMS token valid? The SMS authorization of the QES process is valid for **10 minutes**. > Can a successful identification be "reused" by different companies? There's no technical restrictions on reusing an identification. However, GDPR measures related to data cleanup must be defined. > Is there any timeout set for finishing the bank connection widget? There is a 10-minute timeout.