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 Solaris' Digital Banking API. You'll learn what information is mandatory to collect from your customers and which endpoints and webhooks you need to integrate into your solution.


For a comprehensive overview of onboarding requirements, check the Onboarding requirements guide.

System prerequisites

Before starting the onboarding process, please implement the following prerequisites:

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.

The following screens are required to onboard B2C and freelancer customers for Digital Banking & Cards:

  1. Terms and Conditions
  2. Customer information
  3. Economic interest
  4. Person tax information (Only for customers in Germany)
  5. FATCA indication
  6. Self-declaration as a politically exposed person (PEP). (Only for customers in France, Italy, and Spain)
  7. Compliance screen

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's Terms and Conditions and store the timestamp in the terms_conditions_signed_at field.
  • Collect the customer's consent to data processing and store the timestamp in the data_terms_signed_at field.
  • Collect the customer's economic interest declaration and store the timestamp in the own_economic_interest_signed_at field.
  • Collect the customer's FATCA indication and store it in the fatca_relevant field. Store the timestamp in the fatca_crs_confirmed_at field.

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

Integration overview

The following diagram gives a high-level overview of the integration process for onboarding retail customers (B2C) for Digital Banking & Cards. Click on each step to go to its dedicated section for full instructions:

Customer registration
Legal & compliance requirements
Legal & compliance requir...
Step 1:
Collect customer data
and create person
Step 1:...
Step 2:
Create and verify

mobile number
Step 2:...
Step 3:
Create tax
Step 3:...
Customer identification (KYC) & Due diligence (CDD)
Step 4.1:
Create & trigger
customer identification (KYC)
Step 4.1:...
Step 4.2:
Verify CDD statuses
Step 4.2:...
Step 4.3:
Screen  for FATCA
Step 4.3:...
Abort onboarding
Abort on...
Account & card creation
Step 5:
Create customer
Step 5:...
Step 6:
Create and activate
customer card
Step 6:...
Text is not SVG - cannot display

Onboard retail customers by completing the following steps:

Category Step Description
Customer registration Step 1 Collect the mandatory data points and create a person resource for your customer.
Customer registration Step 2 Create and verify the customer's mobile number.
Tax information Step 3 Collect the customer's tax information and create a tax identification resource.
Customer identification Step 4 4.1. Create and trigger the customer identification process (KYC) and redirect the customer to complete the process with the chosen provider.
4.2. Ensure that the customer passes the customer due diligence process before proceeding with the following steps.
4.3. Ensure that the customer passes the FATCA checks.
Account creation Step 5 Create an account opening request for the customer.
Card creation Step 6 Create and activate the debit card for the customer.

Sequence diagram

To view a larger version of the diagram, right-click the image and click "Open in a new tab."

Diagram: Person onboarding flow


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

Mandatory features

You must integrate all the mandatory features for Digital Banking & Cards highlighted in the Onboarding requirements guide before going live with your solution.

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 to represent your customer.

API reference

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

Related webhook events

Important points about data collection
  • Please consider the special requirements for data collection highlighted in the onboarding requirements guide.
  • 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

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

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.
  • birth_date
  • birth_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

POST /v1/persons

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
  • 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

PATCH /v1/persons/{id}

Click here to view the full API reference

Step 2: Create and verify mobile number

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


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

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

API reference

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

Related webhook events

Testing static values

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

  • Mobile number: +15550101
  • SMS OTP: 212212

POST Create mobile number

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

Request example:

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.

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

Click here to view the full API reference.

POST Authorize mobile number

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

Request example:

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

Response example:

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

Click here to view the full API reference..

POST Confirm mobile number

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

Request example:

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

Response example:

    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": true

Click here to view the full API reference.

Mobile number management

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

Step 3: Create customer tax identification

In this step, collect the relevant tax information from the customer and create a tax identification resource for them.

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, please 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 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:

Related webhook events

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:

POST /v1/persons/{person_id}/tax_identifications

Click here to view the full API reference.

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
ES Test data can be generated from this website

Compliance disclaimer screen

Before beginning the identification process, your solution must display Solaris' compliance disclaimer and collect the customer's agreement.

Please note the UI requirements and legal text mentioned in the Legal and compliance screens guide

Step 4: Complete the customer identification and due diligence process

In this step, you must trigger the Know Your Customer (KYC) process for your customer and ensure they pass all the mandatory screening checks.

4.1. Customer identification (KYC)

All customers must be successfully identified using a suitable KYC method to be onboarded for any of Solaris' products.

Solaris offers different identification methods based on the product, region, and customer type. This guide explains the integration process with video identification with IDnow as the identification method. IDnow is only available to customers, residing in Germany with a supported identification document.

  • For an overview of the suitable KYC method per country, check the onboarding requirements guide, and consult with your Partner Manager about the identification method tailored to your banking use case.

In this step, you must create an identification resource and trigger the identification process for your customer by implementing the following endpoints:

API reference

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

  • The previous link includes all endpoints for different KYC methods. This section includes the relevant endpoints required for video identification with IDnow.
  • Please note the system prerequisites needed for IDnow here.

Related webhook events

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.

Note that this endpoint does not actually trigger the identification process with the provider. Calling the PATCH Request an identification endpoint will trigger the process.

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

4.2 Customer due diligence (CDD)

  • In addition to the identification process, Solaris runs different risk screening and customer vetting checks (i.e., Customer Due Diligence process) on new and existing customers.
  • The result of this process is stored in different properties in the person resource.
  • The status of all the CDD-related properties must be green for the customer to be onboarded.

For more information, check the Customer Due Diligence guide.

4.3 Screening for FATCA indicia

To comply with the 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:

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.


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.

Validty of identification documents (Only 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.
  2. Request the identification for the customer by calling PATCH Request an identification.
  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:

Step 5: Set up customer account


You've successfully completed the customer identification process, and you can now open an account for the customer.

Present the customer with a button to open their account, using the following formulations for the button text:


Order / Open account (subject to a charge)


Bestellen / Konto eröffnen (zahlungspflichtig)

If you wish to use a different text, please consult with your Partner Manager.

Account opening process

To open an account for your customer, visit the following links to find more information about the account opening process:

Step 6: Create and activate card

Now that you have fully onboarded your customer, you can create a card for them. The customer can choose between different card types, such as a physical or a virtual card, with the option to tokenize the card to be used in any e-wallet, such as Google Pay, Apple Pay, or Samsung Pay. Check the Cards Creation and Servicing guide for instructions on how to issue and service cards.

What's next?

Congratulations! You've successfully completed the person onboarding process for Digital Banking and Cards.

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

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 a company's annual financial statement.
KYC_REPORT The KYC report generate after a successful customer identification.
ID_DOCUMENT An person's identification document, such as passport or ID.
SIGNATURE A signature example.
PICTURE A picture or a 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_CHECK A register check.
REGISTER_EXTRACT A business or a company's commercial register excerpt or a similar document.
FOUNDATION_DOCUMENT The foundation document of a company or business.
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 business or a company's shareholders agreement.
SHAREHOLDERS_LIST A business or a company's shareholders list.
TRADING_LICENSE A business or a company's trading license.
TRANSPARENCY_REGISTER_EXTRACT An extract of a 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 are generated. You must redirect the customer to the URL to complete the identification process with IDnow.
pending_failed The identification is currently under review. You cannot offer banking services to the customer at this stage. The identification might eventually turn to successful, but it is unlikely.
successful The video identification was successful. The customer can be onboarded. Please note that the customer's data might have been updated during the identification session.
aborted The customer aborted the identification process. The customer can still video-identify using the same URL.
canceled The provider canceled the video identification. The customer should video-identify again using the same URL.
failed The identification was unsuccessful. You cannot onboard the customer or offer any banking services to them.

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