Onboard a person (Digital Banking & Cards)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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.

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.

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:

Onboard retail customers by completing the following steps:

Sequence diagram

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

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.

• ACCOUNT_BLOCK
• ACCOUNT_CLOSURE
• ACCOUNT_CLOSURE_REQUEST
• BOOKING
• CARD_LIFECYCLE_EVENT
• CARD_AUTHORIZATION
• CARD_AUTHORIZATION_DECLINE_V2
• CARD_AUTHORIZATION_RESOLUTION
• CARD_FRAUD_CASE_PENDING
• CARD_FRAUD_CASE_TIMEOUT
• IDENTIFICATION
• PERSON_CHANGED
• PERSON_DELETED
• PERSON_SEIZURE_CREATED
• PERSON_SEIZURE_DELETED
• PERSON_SEIZURE_FULFILLED
• PERSON_SEIZURE_UPDATED
• PERSON_MOBILE_NUMBER_CREATED
• PERSON_MOBILE_NUMBER_DELETED
• PERSON_TAX_IDENTIFICATION_CHANGED
• POSTBOX_ITEM_CREATED
• POTENTIAL_ACCOUNT_BLOCKING
• SCA_CHALLENGE

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:

• Person resource API reference:
  • POST Create person
  • GET Retrieve a person
  • PATCH Update person

Related webhook events

• PERSON_CHANGED
• PERSON_DELETED

POST Create person

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

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

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.

Mobile number resource

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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

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

Related webhook events

• PERSON_MOBILE_NUMBER_CREATED
• PERSON_MOBILE_NUMBER_DELETED

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

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:

  • POST Create person tax identification
  • GET Retrieve person tax identification
  • PATCH Update person tax identification

Related webhook events

• PERSON_TAX_IDENTIFICATION_CHANGED

POST Create person tax identification

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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:

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 crucial phase, your primary action is to trigger the Know Your Customer (KYC) identification process for the customer using the API. While the customer completes the identification with our provider, Solaris will perform several mandatory background checks, including Customer Due Diligence (CDD) and FATCA screening. Before proceeding to Step 5, you must verify that the overall status checks are successful by retrieving the person resource.

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.

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:

• Customer identification (KYC) API reference

Related webhook events

• IDENTIFICATION

POST Create identification

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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

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

Request example

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

Response example

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

{
    "id": "6dc54352d6793a892e0702850d07b831cidt",
    "reference": null,
    "url": null,
    "status": "created",
    "completed_at": null,
    "method": "idnow",
    "proof_of_address_type": "GAS_BILL",
    "proof_of_address_issued_at": "2022-09-21",
    "language": "DE",
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null
}

Click here to view the full API reference.

GET List supported documents for a person identification

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

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

Request URL

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

Click here to view the full API reference

PATCH Request person identification

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

Request URL

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

Response example

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

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

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

Click here to view the full API reference.

IDnow video identification session

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

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

GET Retrieve person identification

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

Request URL

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

Click here to view the full API reference.

Other identification endpoints

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

4.2 Customer due diligence (CDD)

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:

• GET Retrieve person
• GET Retrieve person identification

Hard criteria

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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.

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:

• Fourthline
• IDnow AutoIdent

Onboarding Readiness Checklist

Before you proceed with opening an account in Step 5, you must retrieve the person resource and verify that all of the following conditions are met. As per the Customer Due Diligence (CDD) guide, any "yellow" or "red" status in the CDD-related fields will block the onboarding of a new customer.

Step 5: Set up customer account

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

English

Order / Open account (subject to a charge)

German

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:

• Account opening guide
• Account opening API reference

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:

Document types

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

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.

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