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
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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.

System prerequisites

Before starting the onboarding process, 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 outlines the integration process for onboarding retail customers. Click on each step to jump to the relevant section.

Sequence diagram

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

Webhooks

Subscribe to the following webhook events to automate your integration. For implementation details, check the webhooks documentation.

Identity and person data

• IDENTIFICATION
• PERSON_CHANGED
• PERSON_DELETED
• PERSON_MOBILE_NUMBER_CREATED
• PERSON_MOBILE_NUMBER_DELETED
• PERSON_TAX_IDENTIFICATION_CHANGED

Accounts and bookings

• BOOKING
• ACCOUNT_BLOCK
• ACCOUNT_CLOSURE
• ACCOUNT_CLOSURE_REQUEST
• POTENTIAL_ACCOUNT_BLOCKING
• POSTBOX_ITEM_CREATED

Cards

• CARD_LIFECYCLE_EVENT
• CARD_AUTHORIZATION
• CARD_AUTHORIZATION_DECLINE_V2
• CARD_AUTHORIZATION_RESOLUTION
• CARD_FRAUD_CASE_PENDING
• CARD_FRAUD_CASE_TIMEOUT

Compliance and seizures

• PERSON_SEIZURE_CREATED
• PERSON_SEIZURE_DELETED
• PERSON_SEIZURE_FULFILLED
• PERSON_SEIZURE_UPDATED

Authentication

• SCA_CHALLENGE

Mandatory features

You must integrate all mandatory features highlighted in the Onboarding requirements guide 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.

Pass this data to Solaris by creating a person resource.

API reference

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

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

Related webhook events

• PERSON_CHANGED
• PERSON_DELETED

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.

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

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

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: Record tax identification

Collect relevant tax information and create a tax identification resource.

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

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

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

Create an identification resource and trigger the process using the following endpoints:

API reference

• Customer identification (KYC) API reference

Related webhook events

• IDENTIFICATION

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

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

Returns an identification object with status created.

{
    "id": "6dc54352d6793a892e0702850d07b831cidt",
    "status": "created",
    "method": "idnow",
    ...
}

Click here to view the full API reference.

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.

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

Click here to view the full API reference

Trigger identification request

Call this endpoint to generate the required tokens and URLs for the IDnow session.

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.

{
    "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.

The IDnow session

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.

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

Click here to view the full API reference.

Other utility endpoints

• List IDnow attempts (Audit log of failed/aborted calls)
• Upload additional documents

4.2 Customer due diligence (CDD)

For details, see 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

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.

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.
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 opening an account, retrieve the person resource and verify all the following conditions. Any "yellow" or "red" status will block onboarding.

Step 5: Open account

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
• Account opening API reference

Step 6: Issue card

Once onboarded, you can create a card for the customer (physical or virtual).

See the Cards Creation and Servicing guide 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: Link the customer's smartphone to their account. This is required for Strong Customer Authentication (SCA).
2. Implement Login & SCA: Set up the flows for logging in and authorizing sensitive actions.

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.