# Onboard a person (Digital Banking & Cards) This guide provides step-by-step instructions for onboarding new retail customers (B2C) for Digital Banking and Cards products using the Solaris API. You will learn which information is mandatory and which endpoints and webhooks to integrate. For a comprehensive overview of onboarding requirements, check the [Onboarding requirements guide](/guides/get-started/onboarding-requirements/). ## System prerequisites Before starting the onboarding process, implement the following prerequisites: ### 1. Technical setup Before starting, ensure your environment is configured for the **Digital Banking** product scope. * **Authentication:** Retrieve your client credentials and set up your OAuth flow. * **Webhooks:** Configure your endpoint to receive event notifications (e.g., incoming transfers, status changes). [View the Technical Setup Guide](/guides/get-started/technical-setup) ### 2. Legal & Compliance screens You must integrate specific consent screens into your signup flow *before* initiating the API onboarding process. **Required Screens:** 1. **Terms & Conditions:** Collect explicit consent to Solaris T&Cs. 2. **Customer Information:** verify personal details. 3. **Economic Interest:** Confirm the customer is acting on their own behalf. 4. **Tax Information:** Collect Tax ID (required for Germany). 5. **FATCA/CRS:** Determine US tax liability. 6. **PEP Declaration:** Self-declaration for Politically Exposed Persons (Required for FR, IT, ES). **Data Storage:** For every consent screen, you must capture a **UTC timestamp** (e.g., `2023-10-27T10:00:00Z`). These timestamps are mandatory fields when creating the `person` resource. | Consent Type | API Field (Person Resource) | | --- | --- | | Terms & Conditions | `terms_conditions_signed_at` | | Data Processing | `data_terms_signed_at` | | Economic Interest | `own_economic_interest_signed_at` | | FATCA/CRS | `fatca_crs_confirmed_at` | [View the Legal Screens Guide](/guides/get-started/onboarding-requirements/1-legal-compliance-screens) ## Integration overview The following diagram outlines the integration process for onboarding retail customers. Click on each step to jump to the relevant section. ```mermaid flowchart TD %% --- Chart Structure --- subgraph P0 ["Phase 0: Prerequisites"] A0("Legal & Compliance
Requirements") end subgraph P1 ["Phase 1: Customer Registration"] A1("Step 1:
Create Person Resource") --> A2("Step 2:
Verify Mobile Number") A2 --> A3("Step 3:
Create Tax Identification") end subgraph P2 ["Phase 2: KYC & CDD"] B1("Step 4.1:
Create & Trigger KYC") --> B2("Step 4.2:
Verify CDD Statuses") B2 --> B3("Step 4.3:
Screen for FATCA Indications") B3 --> B4{KYC/CDD
Check} end subgraph P3 ["Phase 3: Account & Card Creation"] C1("Step 5:
Create Account") --> C2("Step 6:
Create & Activate Card") end D[Abort Onboarding] %% --- Connections between Phases --- P0 --> P1 --> P2 B4 -->|successful| P3 B4 -->|failed| D %% --- Inline Style Definitions --- style A0 fill:#f2f2f2,color:#1b2230,stroke:#c8cdd6,stroke-width:2px style A1 fill:#f2f2f2,color:#1b2230,stroke:#c8cdd6,stroke-width:2px style A2 fill:#f2f2f2,color:#1b2230,stroke:#c8cdd6,stroke-width:2px style A3 fill:#f2f2f2,color:#1b2230,stroke:#c8cdd6,stroke-width:2px style B1 fill:#f2f2f2,color:#1b2230,stroke:#c8cdd6,stroke-width:2px style B2 fill:#f2f2f2,color:#1b2230,stroke:#c8cdd6,stroke-width:2px style B3 fill:#f2f2f2,color:#1b2230,stroke:#c8cdd6,stroke-width:2px style C1 fill:#f2f2f2,color:#1b2230,stroke:#c8cdd6,stroke-width:2px style C2 fill:#f2f2f2,color:#1b2230,stroke:#c8cdd6,stroke-width:2px style B4 fill:#dedbd3,color:#1b2230,stroke:#5e6a7a,stroke-width:2px style D fill:#ffc2ad,color:#1b2230,stroke:#5d5746,stroke-width:2px %% --- Clickable Links --- click A0 "#system-prerequisites" click A1 "#step-1-collect-customer-data" click A2 "#step-2-verify-mobile-number" click A3 "#step-3-record-tax-identification" click B1 "#41-customer-identification-kyc" click B2 "#42-customer-due-diligence-cdd" click B3 "#43-screening-for-fatca-indicia" click C1 "#step-5-open-account" click C2 "#step-6-issue-card" ``` | Category | Step | Description | | --- | --- | --- | | **Registration** | [Step 1](#step-1-collect-customer-data) | Collect mandatory data and create a person resource. | | **Registration** | [Step 2](#step-2-verify-mobile-number) | Create and verify the customer's mobile number. | | **Tax Info** | [Step 3](#step-3-record-tax-identification) | Collect tax information and create a tax identification resource. | | **Identification** | [Step 4](#step-4-identify-customer-kyc-and-due-diligence) | Trigger the identification process (KYC) and ensure the customer passes background checks (CDD, FATCA). | | **Account** | [Step 5](#step-5-open-account) | Create an account opening request. | | **Cards** | [Step 6](#step-6-issue-card) | Create and activate a debit card. | ### Sequence diagram To view a larger version, right-click the image and select "Open in a new tab". ![Diagram: Person onboarding flow](/assets/person-onboarding.d526027c9855455a5d9adb0aaeab8986a13a72d296c3d81ef38e23745b360ce3.71c3202d.svg) ### Webhooks Subscribe to the following webhook events to automate your integration. For implementation details, check the [webhooks documentation](/api-reference/webhooks/). ### Identity and person data * [`IDENTIFICATION`](/api-reference/onboarding/webhooks/webhook-events/paths/identification/post) * [`PERSON_CHANGED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_changed/post) * [`PERSON_DELETED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_deleted/post) * [`PERSON_MOBILE_NUMBER_CREATED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_mobile_number_created/post) * [`PERSON_MOBILE_NUMBER_DELETED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_mobile_number_deleted/post) * [`PERSON_TAX_IDENTIFICATION_CHANGED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_tax_identification_changed/post) ### Accounts and bookings * [`BOOKING`](/api-reference/onboarding/webhooks/webhook-events/paths/booking/post) * [`ACCOUNT_BLOCK`](/api-reference/onboarding/webhooks/webhook-events/paths/account_block/post) * [`ACCOUNT_CLOSURE`](/api-reference/onboarding/webhooks/webhook-events/paths/account_closure/post) * [`ACCOUNT_CLOSURE_REQUEST`](/api-reference/onboarding/webhooks/webhook-events/paths/account_closure/post) * [`POTENTIAL_ACCOUNT_BLOCKING`](/api-reference/onboarding/webhooks/webhook-events/paths/potential_account_blocking/post) * [`POSTBOX_ITEM_CREATED`](/api-reference/onboarding/webhooks/webhook-events/paths/postbox_item_created/post) ### Cards * [`CARD_LIFECYCLE_EVENT`](/api-reference/onboarding/webhooks/webhook-events/paths/card_lifecycle_event/post) * [`CARD_AUTHORIZATION`](/api-reference/onboarding/webhooks/webhook-events/paths/card_authorization/post) * [`CARD_AUTHORIZATION_DECLINE_V2`](/api-reference/onboarding/webhooks/webhook-events/paths/card_authorization_decline_v2/post) * [`CARD_AUTHORIZATION_RESOLUTION`](/api-reference/onboarding/webhooks/webhook-events/paths/card_authorization_resolved/post) * [`CARD_FRAUD_CASE_PENDING`](/api-reference/onboarding/webhooks/webhook-events/paths/card_fraud_case_pending/post) * [`CARD_FRAUD_CASE_TIMEOUT`](/api-reference/onboarding/webhooks/webhook-events/paths/card_fraud_case_timeout/post) ### Compliance and seizures * [`PERSON_SEIZURE_CREATED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_seizure_created/post) * [`PERSON_SEIZURE_DELETED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_seizure_deleted/post) * [`PERSON_SEIZURE_FULFILLED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_seizure_fulfilled/post) * [`PERSON_SEIZURE_UPDATED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_seizure_updated/post) ### Authentication * [`SCA_CHALLENGE`](/api-reference/onboarding/webhooks/webhook-events/paths/sca_challenge/post) ### Mandatory features You must integrate all mandatory features highlighted in the [Onboarding requirements guide](/guides/get-started/onboarding-requirements/6-mandatory-features/#digital-banking--cards) before going live. ## Step 1: Collect customer data Collect mandatory data points in your sign-up flow, including timestamps for the customer's consent to the [legal and compliance screens](#system-prerequisites). Pass this data to Solaris by creating a [person resource](/guides/get-started/onboarding-requirements/2-data-collection/#customer-data-resource-types). **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/webhook-events/paths/person_changed/post) - [`PERSON_DELETED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_deleted/post) Important points about data collection - Review the special requirements in the [Onboarding requirements guide](/guides/get-started/onboarding-requirements/2-data-collection/#important-considerations-for-data-collection). - Submit information exactly as it appears in official documents. - **Sandbox Testing:** 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. - **Privacy:** Do not use real personal data when testing in Sandbox. ### Create person Important points - The mandatory data points required for retail customers may differ depending on the country in which you're opening the account. The following example outlines the mandatory fields for Germany. For information about other countries, please refer to the [Onboarding requirements guide](/guides/get-started/onboarding-requirements/2-data-collection/#retail-customers-b2c) Call this endpoint to create a person resource for your customer, and add the following mandatory data points in the request body: **Mandatory data points for retail customers in Germany** - `salutation` - `first_name` - `last_name` - `address` - `line_1` - `line_2` - `postal_code` - `city` - `country` - `mobile_number`: This field is only used to pass the mobile number to our KYC provider IDnow for the Videoident KYC flow. To create and verify a mobile number for your customer, you need to use the dedicated [mobile number endpoints](https://docs.solarisgroup.com/api-reference/onboarding/persons/#tag/Person-mobile-numbers). - `birth_date` - `birth_city` (must be a valid city) - `birth_country` - `nationality` - `employment_status` - `fatca_relevant` - `fatca_crs_confirmed_at` - `terms_conditions_signed_at` - `data_terms_signed_at` - `own_economic_interest_signed_at` - `tax_information` - `marital_status` **Request URL** ```shell POST /v1/persons ``` [Click here to view the full API reference.](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons/post) ### 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` Important **Restricted Updates:** * Fields not mentioned in this list can only be updated via Customer Support. **Freelancer & Self-Employed Requirements (B2C):** * If a customer changes their `employment_status` to `FREELANCER` or `SELF_EMPLOYED`, you must include **one** of the following in the request to avoid an error: 1. The customer's `nace_code` (Recommended for data quality). 2. Set `industry` and `industry_key` to `null`. **Request URL** ```shell PATCH /v1/persons/{id} ``` **Request example** * [API Reference: Update person](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons~1%7Bid%7D/patch) ## Step 2: Verify mobile number Collect the customer's mobile number, create a mobile number resource, and verify it via SMS OTP. The customer must enter the OTP in your frontend to complete verification. Important This data point is **required** for all customers. ### 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/webhook-events/paths/person_mobile_number_created/post) - [PERSON_MOBILE_NUMBER_DELETED](/api-reference/onboarding/webhooks/webhook-events/paths/person_mobile_number_deleted/post) 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. You must include the customer's `person_id` in the request URL. **Request URL** ```shell POST /v1/persons/{person_id}/mobile_number ``` **Request example** ```json { "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 URL** ```shell POST /v1/persons/{person_id}/mobile_number/authorize ``` **Request example** ```json { "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 URL** ```shell POST /v1/persons/{person_id}/mobile_number/confirm ``` **Request example** ```json { "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) For more information about how to manage mobile numbers (e.g., changing or deleting a number), check the related [mobile number management guide](/guides/digital-banking/mobile-number-management). ## Step 3: Record tax identification Collect relevant [tax information](/guides/get-started/onboarding-requirements/3-tax-information/) and create a tax identification resource. ### API reference Important points about tax information Submitting the tax information of your customers is a requirement to open a bank account in all of Solaris branches. However, note the following: * You can open the bank account for customers in Germany (DE branch) before they provide tax information. However, you must submit the customer's tax information to Solaris within **90 days** of opening the account. Otherwise, Solaris will block the customer's account with the reason `MISSING_TAX_INFORMATION` until you submit the required tax information. * If a customer has multiple tax residencies (i.e., taxable in multiple countries), you must create a separate tax identification resource for each tax residency and specify **only** one of them as `primary`. * The first `tax_identification` to be submitted for a `person` or a `business` must be the primary tax identification. If another `tax_identification` with the value of `primary` set to `true` is created, it will set the `primary` value of the previously created `tax_identification` to `false`. * A `person` or `business` may only have one `tax_identification` per `country`. * When creating a `tax_identification`, explicitly collect the `country` value from the user and do not default to their physical residence (i.e., the `country` property of the `person` resource). * Check the [Onboarding requirements guide](/guides/get-started/onboarding-requirements/3-tax-information#tax-identification-number-tin-per-country) for more information about the TIN requirements per country. For a complete list of endpoints, properties, and examples related to the `person tax identification` resource, visit the following links: - [Person tax identifications API reference](/api-reference/onboarding/persons/#tag/Person-tax-identifications): - [POST Create person tax identification](/api-reference/onboarding/persons/#tag/Person-tax-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1tax_identifications/post) - [GET Retrieve person tax identification ](/api-reference/onboarding/persons/#tag/Person-tax-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1tax_identifications~1%7Bid%7D/get) - [PATCH Update person tax identification ](/api-reference/onboarding/persons/#tag/Person-tax-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1tax_identifications~1%7Bid%7D/patch) **Related webhook events** - [PERSON_TAX_IDENTIFICATION_CHANGED](/api-reference/onboarding/webhooks/webhook-events/paths/person_tax_identification_changed/post) #### POST Create person tax identification Call this endpoint to create a person tax identification for the customer with the `person_id` specified in the request URL. Collect the following tax information from your customers and pass them to Solaris in the request body: - `number` - `country` - `primary` If the customer has not submitted their TIN to your solution yet (i.e., the value of `number` is `null`), then include the following properties in the request: - `reason_no_tin`: Possible values are `NOT_ASSIGNED_YET`, `NOT_ASSIGNED_BY_COUNTRY`, `OTHER`. - `reason_description`: Applies only if the `reason_no_tin` is `OTHER`. - `tax_id_type`: (Only for Spain) Possible values are `NIE` and `NIF`. **Request example:** ```shell POST /v1/persons/{person_id}/tax_identifications ``` [Click here to view the full API reference.](/api-reference/onboarding/persons/#tag/Person-tax-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1tax_identifications/post) ### Tax ID testing data You can use the following test values for the TIN to test these endpoints on Sandbox: | Country | TIN testing values | | --- | --- | | DE | 48954371207 | | FR | 3023217600053 | | IT | SSSNNN31B28X000C | | ES | Test data can be generated from this [website](https://testingdatagenerator.com/doi.html) | ## Compliance disclaimer screen Before starting identification, your solution must display the Solaris compliance disclaimer and collect the customer's agreement. Refer to the UI requirements and legal text in the [Legal and compliance screens guide](/guides/get-started/onboarding-requirements/1-legal-compliance-screens/#compliance-disclaimer-screen). ## Step 4: Identify customer (KYC) and due diligence In this phase, you trigger the Know Your Customer (KYC) process. While the customer completes identification, Solaris performs mandatory background checks (Customer Due Diligence and FATCA). Before proceeding to account creation, you must verify that all status checks are successful. ### 4.1 Customer identification (KYC) All customers must be successfully identified to use Solaris products. Solaris offers different methods based on product, region, and customer type. This guide describes video identification with IDnow (available for customers residing in Germany with supported documents). Consult the [onboarding requirements guide](/guides/get-started/onboarding-requirements/5-kyc/#digital-banking--cards) for suitable KYC methods per country, and contact your Partner Manager to select the best method for your use case. Create an identification resource and trigger the process using the following endpoints: **API reference** - [Customer identification (KYC) API reference](/api-reference/identity/identifications) Prerequisites - This guide focuses on video identification with **IDnow**. - Ensure you have completed the [IDnow technical prerequisites](/guides/kyc/videoident/#idnow-integration) (e.g., mobile SDKs or web redirects). **Related webhook events** - [`IDENTIFICATION`](/api-reference/onboarding/webhooks/webhook-events/paths/identification/post) ### Create identification Call this endpoint to initialize the identification process. You must specify the method (`idnow`) and the customer's preferred language. **Required fields:** - `method`: Set to `idnow`. - `language`: `EN` or `DE`. - `proof_of_address_type`: Required if the ID document does not show the address (e.g., Passport). - `proof_of_address_issued_at`: Required if providing a proof of address (must be < 6 months old). Creating the resource does **not** start the video call. You must trigger it in the next step. **Request example** ```json // 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** Returns an identification object with status `created`. ```json { "id": "6dc54352d6793a892e0702850d07b831cidt", "status": "created", "method": "idnow", ... } ``` [Click here to view the full API reference](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications/post). Custom Flows The method `idnow_custom` allows for a customized IDnow flow. If you are interested in offering this to your customers, contact your Partner Manager. ### Check supported documents Before redirecting the customer, check which documents are supported for their country. This avoids user frustration if they attempt to use an unsupported ID. **Request URL** ```shell GET /v1/persons/{person_id}/identifications/{id}/supported_documents ``` [Click here to view the full API reference](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1supported_documents/get) ### Trigger identification request Call this endpoint to generate the required tokens and URLs for the IDnow session. **Request URL** ```shell PATCH /v1/persons/{person_id}/identifications/{id}/request ``` **Response example** The status changes to `pending`. The response contains two critical fields depending on your integration type: - `url`: Use this for **Web** integrations (redirect the user here). **Valid for 14 days.** - `reference`: Use this token for **Mobile SDK** (iOS/Android) integrations. ```json { "id": "6dc54352d6793a892e0702850d07b831cidt", "reference": "TST-KCCEY", "url": "[https://go.test.idnow.de/solarisbankvideoidentsandbox/identifications/](https://go.test.idnow.de/solarisbankvideoidentsandbox/identifications/)...", "status": "pending", ... } ``` [Click here to view the full API reference](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1request/patch). ### The IDnow session ```mermaid flowchart LR A[Start] --> B{Integration Type?} B -- Web --> C[Redirect User to 'url'] B -- Mobile SDK --> D[Init SDK with 'reference'] C --> E[IDnow Session] D --> E E --> F{Outcome} F -- Success --> G[Webhook: IDENTIFICATION] F -- Failure --> H[Retry / Abort] ``` Once you redirect the customer (Web) or initialize the SDK (Mobile), the IDnow session begins. 1. **Consent & Setup:** The customer lands on an IDnow-branded page. They must consent to Terms & Conditions and confirm they have a valid ID document ready. 2. **Mobile Verification:** The customer provides a mobile number. The IDnow agent sends an SMS OTP to this number during the call to verify possession. 3. **Video Call:** The agent connects via video to verify the customer's face and ID document live. 4. **Data Update:** If the agent detects missing or incorrect data (e.g., name spelling), they will update the record directly. These changes are automatically reflected in the `person` resource. ### Retrieve identification status Once the webhook `IDENTIFICATION` signals success, retrieve the final data. Use the `?include_documents=true` query parameter to download the images of the ID document and the user's face. **Request URL** ```shell GET /v1/persons/{person_id}/identifications/{id} ``` [Click here to view the full API reference](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D/get). ### Other utility endpoints - [List IDnow attempts](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1idnow_attempts/get) (Audit log of failed/aborted calls) - [Upload additional documents](/api-reference/onboarding/persons/#tag/Person-documents/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1document_upload/post) ### 4.2 Customer due diligence (CDD) In addition to identification, Solaris runs risk screening and customer vetting checks (CDD). * Results are stored in the `person` resource. * All CDD-related properties must be `green` to onboard the customer. For details, see the [Customer Due Diligence guide](/guides/kyc/cdd). ### 4.3 Screening for FATCA indicia To comply with the [Foreign Account Tax Compliance Act (FATCA)](https://www.irs.gov/businesses/corporations/foreign-account-tax-compliance-act-fatca), Solaris is required to perform checks to determine whether the customer is subject to US tax law. These checks are in addition to the self-declaration during the Legal and Compliance screen. To perform the FATCA checks, parse the `person` and `identification` resources using the following endpoints: - [GET Retrieve person](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons~1%7Bid%7D/get) - [GET Retrieve person identification](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D/get) #### Hard criteria To determine the customer's FATCA relevance, you must screen for the following **hard criteria**: - Has the customer provided a US passport as their identification document? Check the `legitimation_country` attribute on the identification resource. - Is the customer a citizen of the US? Check the `nationality` attribute. - Has the customer provided a residential address in the US, the US Minor Outlying Islands, or the US Virgin Islands? Check the `country` attribute. - Was the customer born in the US, the US Minor Outlying Islands, or the US Virgin Islands? Check the `birth_country` attribute. **When to reject the customer** If any of these hard criteria attributes have the value of `US` or `USA`, **you must deny banking services to the customer and stop the onboarding process**. Failure to screen for these hard FATCA criteria may cause ongoing operational burdens for Solaris customer support. #### Soft criteria To further determine the customer's FATCA relevance, screen for the following **soft criteria**: - Has the customer provided a US mobile number? Check the `mobile_number` attribute. US mobile numbers have a country code of +1. - Is the customer's only address a PO box or a c/o address? Check the `address_line_1` and `address_line_2` attributes. **When to reject the customer** - If the answer is "Yes" to any of the **soft criteria,** ask the customer to clarify their phone number and/or address. - If the customer provides a non-US phone number and a physical address, you may onboard them. - If the customer **does not** provide a non-US phone number and a physical address, you **may not onboard them.** Failure to screen for soft FATCA criteria may cause ongoing operational burdens for Solaris customer support. Important Note that Solaris periodically checks FATCA relevance for existing customers. If a customer's FATCA relevance changes to `true`, Solaris's Customer Support team will provide further instructions. ### Validity of identification documents (Spain & Italy) To comply with regulatory requirements, Solaris must keep copies of valid identification documents for active customers in its **Italy** and **Spain** branches. This requirement applies to the following customer segments: - Retail customers - Freelancers & Sole proprietors - Businesses' legal representatives - Authorized persons on a business or a retail account **How will you be notified of the expiry of ID documents?** In Italy and Spain, Solaris stores the expiry date of a customer's identification document and calculates a follow-up date to notify you before it expires. You'll receive a webhook notification on the event `POTENTIAL_ACCOUNT_BLOCKING` 30 days before the expiry date, and then every 30 days until 90 days after the expiry. The webhook payload includes the `blocking_date`, which is the date by which the account will be blocked if the customer has not identified again with a valid ID document, and the reason for the account blocking is set to `IDENTIFICATION_DOCUMENT_EXPIRED`. **What should you do?** After receiving a notification on the `POTENTIAL_ACCOUNT_BLOCKING` webhook event, you should take the following steps: 1. Create a new identification resource for the customer and specify the identification `method` using the [POST Create an identification](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications/post). 2. Request the identification for the customer by calling [PATCH Request an identification](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1request/patch). 3. Notify the customer that they must complete the KYC flow with their new valid ID document. 4. After successful KYC, Solaris will store the expiry date of the new ID document and calculates a new follow-up date. If the customer did not identify with a valid ID document within 90 days after the expiry date, the customer's account will be blocked with the reason `IDENTIFICATION_DOCUMENT_EXPIRED`. If a new ID document is submitted, the account will be unblocked. **Which KYC method to use?** For the re-identification due to expired ID documents, you can choose between the following methods: - [Fourthline](/guides/kyc/fourthline/) - IDnow AutoIdent ### Onboarding readiness checklist Before opening an account, retrieve the `person` resource and verify **all** the following conditions. Any "yellow" or "red" status will block onboarding. | Check | Resource & Field | Required "Green" Status | | --- | --- | --- | | **KYC Identification** | `identification.status` | Must be `successful` | | **Mobile Number** | `mobile_number.verified` | Must be `true` | | **Tax Identification** | `tax_identifications` | At least one primary record must exist.*(For DE branch, can be provided within 90 days)* | | **FATCA Screening** | Various `person` fields | Must have no hard or unresolved soft criteria | | **Customer Screening** | `person.screening_progress` | Must be `SCREENED_ACCEPTED` | | **Risk Classification** | `person.risk_classification_status` | `NORMAL_RISK`, `RISK_ACCEPTED`, or `SCORING_NOT_REQUIRED` | | **Customer Vetting** | `person.customer_vetting_status` | `NO_MATCH`, `RISK_ACCEPTED`, or `VETTING_NOT_REQUIRED` | ## Step 5: Open account Congratulations You have successfully completed the identification process. You can now open an account for the customer. Present the customer with a button to open their account using the specific formulations below: **English** > Order / Open account (subject to a charge) **German** > Bestellen / Konto eröffnen (zahlungspflichtig) (Consult your Partner Manager if you wish to use different text.) ### Account opening process * [Account opening guide](/guides/digital-banking/account-opening/) * [Account opening API reference](/api-reference/onboarding/account-creation/#tag/Account-opening) ## Step 6: Issue card Once onboarded, you can create a card for the customer (physical or virtual). See the [Cards Creation and Servicing guide](/guides/cards/creation-and-servicing/#how-to-issue-a-card) for instructions. ## What's next? Congratulations! You have successfully created a person resource, opened an account, and issued a card. **Critical Next Step: Authentication** The customer cannot log in or authorize payments yet. You must now implement the security framework: 1. **[Bind a Device](/guides/authentication/device-binding/):** Link the customer's smartphone to their account. * **Choice:** You can implement either the **SMS OTP** flow or the **Activation Code (QR)** flow. * **Requirement:** This binding is mandatory for Strong Customer Authentication (SCA). 2. **[Implement Login & SCA](/guides/authentication/strong-customer-authentication/):** Set up the flows for logging in and authorizing sensitive actions using the bound device. ## Appendix I: Enums #### Annual income range To set the value of `annual_income_range`, you may offer the customer a drop-down list with the following numeric values for each range: | Range | Value | | --- | --- | | `RANGE_1` | < 20000 | | `RANGE_2` | 20000 - 40000 | | `RANGE_3` | 40000 - 60000 | | `RANGE_4` | 60000 - 100000 | | `RANGE_5` | 100000 - 200000 | | `RANGE_6` | 200000 - 400000 | | `RANGE_7` | > 400000 | #### Document types The following table includes the possible values for the field `document_type` and their descriptions. | Enum | Description | | --- | --- | | `ANNUAL_FINANCIAL_STATEMENT` | A business or company's annual financial statement. | | `KYC_REPORT` | The KYC report generated after successful customer identification. | | `ID_DOCUMENT` | A person's identification document, such as a passport or ID card. | | `SIGNATURE` | A signature sample. | | `PICTURE` | A picture or scanned document of any other type. | | `QES_DOCUMENT` | A document related to a Qualified Electronic Signature (QES). | | `SIGNED_CONTRACT` | A signed contract of any kind. | | `SIGNED_QES_DOCUMENT` | A document signed by a Qualified Electronic Signature (QES). | | `REGISTER_APPLICATION` | A document proving the application for registration (Gründungsurkunde), used for companies "in formation". | | `REGISTER_CHECK` | A register check. | | `REGISTER_EXTRACT` | A commercial register excerpt or similar document. | | `FOUNDATION_DOCUMENT` | The foundation document of a company or business. | | `SCHUFA_COMPACT_REPORT` | A compact SCHUFA report. | | `SCHUFA_GWG_REPORT` | A GWG (Money Laundering Act) SCHUFA report. | | `SCHUFA_FULL_REPORT` | A full SCHUFA report about a person. | | `SCHUFA_SHORT_REPORT` | A short SCHUFA report about a person. | | `CREDIT_AGENCY_REPORT` | A report issued by a credit agency. | | `SHARE_HOLDERS_AGREEMENT` | A shareholder agreement. | | `SHAREHOLDERS_LIST` | A list of shareholders. | | `TRADING_LICENSE` | A trading license. | | `TRANSPARENCY_REGISTER_EXTRACT` | An extract from the transparency register. | | `INVOICE` | An invoice of any kind. | | `OTHER` | Any other type of document. | | `VIDEO` | A video of any kind. | | `VAT_CERTIFICATE` | VAT registration certificate. | #### IDnow 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. | Status | Description | | --- | --- | | `created` | The identification resource has been created for the customer. | | `pending` | The identification process has been triggered, and the video identification URL and reference have been generated. Redirect the customer to the URL to complete the identification. | | `pending_failed` | The identification is currently under review by the provider. You **cannot** offer banking services to the customer at this stage. | | `successful` | The video identification was successful. The customer can be onboarded. Note that the customer's data might have been updated during the identification session. | | `aborted` | The customer aborted the identification process. They can retry using the same URL. | | `canceled` | The provider canceled the video identification. The customer should retry using the same URL. | | `failed` | The identification was unsuccessful. You **cannot** onboard the customer or offer any banking services to them. | | `expired` | The identification link has expired (validity period passed). You must create a new identification request. | IDnow provides a reason whenever the identification has a `canceled` or `aborted` status. No reason is disclosed for the final `failed` status.