Decoupled cards for consumers

This guide contains all the relevant information about Solaris' Decoupled Cards product, including the key concepts and the necessary endpoints for creating, activating, and servicing decoupled card applications.

Introduction

Product specifications

Solaris' Decoupled Cards enable customers to benefit from a modern debit card without opening a new bank account or manually transferring funds to use the card to make purchases.

A decoupled card is a debit card with an attached credit limit set according to a risk-based scoring system and linked to the customer's external bank account (i.e., the reference account). Customers can use the available limit to make purchases using the card. The negative balance is settled daily from the customer's external reference account via SEPA Direct Debit (SDD).

Decoupled cards are subject to account and transaction fees, and they can be issued in physical or virtual form. They are currently available to retail customers in Germany with a limit from EUR 100 to EUR 1,000, depending on the customer's credit score.

note

Due to its limited functionality, a decoupled card is NOT considered a credit card or a payments account.

User journey

A decoupled card combines a card, account, and credit limit. The user journey looks as follows:

  1. The customer applies for a decoupled card with Solaris and agrees to the terms and conditions, credit checks, and account snapshot.
  2. After passing the credit checks stage, the customer is offered a decoupled card with a specific credit limit (i.e., an overdraft limit).
  3. The customer goes through the customer identification process (KYC).
  4. After a successful identification, you will create an internal bank account (with type DECOUPLED_CARD_PERSONAL) for the customer. The offered credit limit is attached to this account and linked to the associated debit card.

    • Note This account is only used in the context of a decoupled card and is not considered a full payments account.
  5. The customer specifies an external reference account and signs a SEPA Direct Debit (SDD) mandate, which authorizes Solaris to debit the reference account with an SDD whenever the decoupled card credit limit is used. The SDD amount equals the used amount.
  6. Whenever the customer uses the card credit limit to make a purchase or withdrawal, the internal account balance goes negative. Afterward, an SDD of the used amount will be debited from the reference account on the same day and transferred to the customer's internal account to settle the negative balance.

Decoupled card usage

The customer can use the decoupled card in the following cases:

  • Card payments and ATM cash withdrawals using the credit limit available on the internal account.
  • Topping up the card's account with cash by transferring money from their reference account to the internal account.
  • Transferring any positive balance on the card's account back to their reference account.
note

Customers cannot transfer cash from the credit limit balance on the internal account to their reference account.

SDD orchestration

The SEPA Direct Debit (SDD) to settle the internal account balance is pulled from the customer's external reference account. The SDD amount equals the amount the customer used from the card's credit limit.

Depending on your needs, you can choose between two options for how the SDD should be orchestrated:

  • Automatic SDD orchestration: In this setup, Solaris handles the money flow between the reference account and the internal account. The SDD is triggered automatically each day for any negative balance. You do not need to implement any endpoints.
  • Manual SDD orchestration: In this setup, you can have more control over when the SDD is triggered and the amount to be debited from the customer's reference account. However, this setup requires additional configurations. Consult your Partner Manager for more information.

Accounts

A decoupled card involves different bank accounts:

  1. Reference account: The customer's external bank account from which the SDD is pulled to settle the internal account balance when the customer makes purchases with the decoupled card.

    • Note: Customers can have multiple reference accounts tied to their decoupled card. Consult your Partner Manager for more information about setting up multiple reference accounts.
  2. Internal account: An internal Solaris account created for a decoupled card. The overdraft (i.e., the credit limit available on the card) is attached to this account. Solaris credits the funds from the customer's reference account to this account via SDD to settle any negative balance.
  3. (Optional) Round-up account: The customer can opt for a round-up account associated with the decoupled card. The customer specifies a round-up amount for each purchase (e.g., rounding up the purchase amount to the nearest value). In this case, the SDD includes the purchase amount (transferred to the internal account) and the round-up amount (transferred to the round-up account).

    • Note: This account can only be used in the manual SDD orchestration setup.

Credit scoring

Solaris uses an automated credit scorer to make informed credit decisions on consumer decoupled card applications. The scorer collects and analyzes different information, such as the customer's financial information, credit data, transaction history, and outstanding loans, to assess their creditworthiness and determine their risk level and credit eligibility.

Based on the various credit checks conducted throughout the application lifecycle, the scorer estimates the probability of default (PD), determines whether the customer is eligible for a decoupled card, and specifies the limit to grant them.

Which information does the credit scorer use?

The credit scorer receives self-declared financial information, credit records, account snapshots, and other necessary information. Then, throughout the lifecycle of a decoupled card application, the scorer provides different responses based on the information provided during each application stage.

The scorer performs different credit checks throughout the application lifecycle, such as:

  • Initial scoring: Checks the credit record obtained from external credit bureaus, such as SCHUFA.
  • Verification: Checks the account snapshot to verify the financial information provided in the decoupled card application.

System prerequisites

Before starting the person onboarding process, you must implement the following requirements:

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.

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

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


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.


Integration flow

Integration steps

User registration

  1. Collect the mandatory customer data and consent to the legal and regulatory requirements in your sign-up flow, and create a person resource for your customer by completing Step 1.
  2. Create and verify the customer's mobile number by completing Step 2.
  3. Implement the device binding process for the customer.
  4. Create a person tax identification by completing Step 3.

SDD collection application

  1. Create a credit record for the customer by completing Step 4.
  2. Create SDD collection application by completing Step 5.
  3. Create an account snapshot and attach it to the SDD application by completing Step 6.

Customer identification and due diligence

  1. Create an identification resource for the customer and specify the identification method by completing Step 7.
  2. Redirect the customer to complete the chosen identification process.
  3. Ensure that the customer is successfully identified and passes the risk screening in the due diligence process before proceeding with the following steps.

Accounts and card setup

  1. Create an internal account for the customer and link it to the SDD collection application by completing Step 8.
  2. Create the reference account and SDD mandate by completing Step 9.
  3. Create and activate the decoupled card for the customer by completing Step 10.

You can find details descriptions of these steps and their related endpoints in the following sections.


Step 1: Collect customer data and create person resource

In this step, you must collect the mandatory data points from the customer in your sign-up flow, including all the timestamps of the customer's consent to the legal and compliance screens. Afterward, pass all the data points to Solaris by creating a person resource.

What is a person resource?

The person resource represents the customer's personal and financial data at Solaris. It contains all mandatory customer data, as well as links to other resources created for the customer (e.g., accounts, tax identifications).

API reference

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

Related webhook events

Important points about the person resource
  • The mandatory data points for this endpoint depend on various factors, such as the product, customer type (e.g., retail customers, freelancers, legal representatives, or beneficial owners), and country.
  • You must submit the information exactly as it appears in official documents.
  • Solaris validates the values entered for the fields first_name and last_name. Please ensure your solution applies the following sanitization rules to these fields:

    • It must not be longer than 50 characters.
    • It must not start with a whitespace.
    • It must not include any symbols or emojis.
  • When testing this process on Sandbox, please ensure that you create as many unique person resources as possible (i.e., unique values for first_name, last_name, birth_city, and birth_date). If you create more than 1000 identical person resources, then the API will return a 400 error.

Note about branching

Solaris may restrict the residency countries that are allowed for customers onboarding to a specific branch. If you attempt to create a customer with a residency country that is not allowed for the given branch, the API will return a 400 error and provide a list of allowed residency countries.

Example:

Copy
Copied
{
    "errors": [
        {
            "id": "24b0e02a-341d-40bc-9e52-0d9f8cc8c6eb",
            "status": 400,
            "code": "invalid_model",
            "title": "Invalid Model",
            "detail": "country Residency Country is not allowed for this branch,allowed residency country values for branch \"null\" are [\"DE\", \"FR\"]",
            "source": {
                "field": "country",
                "message": "Residency Country is not allowed for this branch,allowed residency country values for branch \"null\" are [\"DE\", \"FR\"]"
            }
        }
    ]
} 

Please contact your Partner Manager for information about which residency countries are allowed for your branch(es).

attention
  • Each country has its own set of required data points for this request. The example below shows the required data points for retail customers in Germany. For other countries, see Appendix II: Required data points by country for more details.

POST Create person

This endpoint creates a person resource for your customer. Add the following mandatory data points in the request body of this endpoint:

Important

The customer must submit the information exactly as it appears in official documents.

Mandatory data points for retail customers in Germany

  • salutation: Note: MR for male, MS for female, null for gender-neutral.
  • first_name (including all middle names as printed on the ID document)
  • last_name (including all name parts as printed on the ID document)
  • address

  • contact_address (OPTIONAL To be used only if the customer's current address is younger than two years.)
  • mobile_number: Must be verified.
  • birth_date
  • birth_city
  • birth_country (ISO 3166-1 alpha-2 codes)
  • nationality (ISO 3166-1 alpha-2 codes)
  • employment_status (Possible values below):

    • EMPLOYED
    • UNEMPLOYED
    • PUBLIC_SECTOR_EMPLOYEE
    • PROFESSIONAL_SOLDIER
    • FREELANCER
    • HOUSEWORK
    • APPRENTICE
    • MANAGEMENT
    • RETIRED
    • STUDENT
    • SELF_EMPLOYED
    • MILITARY_OR_COMMUNITY_SERVICE
  • fatca_relevant
  • fatca_crs_confirmed_at (UTC timestamp)
  • terms_conditions_signed_at (UTC timestamp)
  • data_terms_signed_at (UTC timestamp)
  • own_economic_interest_signed_at (UTC timestamp)
  • tax_information

    • tax_assessment
    • marital_status
  • iban: Only required for Bankident.
attention

Solaris validates the values entered for the fields first_name and last_name. Please ensure your solution applies the following sanitization rules to these fields:

  • It must not be longer than 50 characters.
  • It must not start with a whitespace.
  • It must not include any symbols or emojis.

Request example

Copy
Copied
// POST /v1/persons
{
   "salutation": "MS",
   "first_name": "Theresa",
   "last_name": "Klemm",
   "address": {
       "line_1": "Leopoldstraße",
       "line_2": " 96",
       "postal_code": "13347",
       "city": "Berlin",
       "country": "DE",
       "state": "BE"
   },
   "contact_address": {
       "line_1": "Ostenderstraße",
       "line_2": " 70",
       "postal_code": "13353",
       "city": "Berlin",
       "country": "DE",
       "state": "BE"
   },
   "email": "theresa@klemm.com",
   "mobile_number": "+49301234567",
   "birth_date": "1985-12-14",
   "birth_city": "Berlin",
   "birth_country": "DE",
   "nationality": "DE",
   "employment_status": "EMPLOYED",
   "tax_information": {
       "tax_assessment": "SEPARATE",
       "marital_status": "MARRIED"
   },
   "fatca_relevant": false,
   "fatca_crs_confirmed_at": "2022-01-01T00:00:00Z",
   "terms_conditions_signed_at": "2022-01-01T00:00:00Z",
   "data_terms_signed_at": "2022-01-01T00:00:00Z",
   "iban": "DE43110101005555555555"
}

Response example

The API returns a person object with a unique id. You will use this id in subsequent API calls as the value of person_id throughout the remainder of this guide.

Copy
Copied
{
    "id": "84b3b4e6c7a4082cc73c5bd0e096ee88cper",
    "salutation": "MS",
    "title": null,
    "first_name": "Theresa",
    "last_name": "Klemm",
    "address": {
        "line_1": "Leopoldstraße",
        "line_2": " 96",
        "postal_code": "13347",
        "city": "Berlin",
        "country": "DE",
        "state": "BE"
    },
    "contact_address": {
        "line_1": "Ostenderstraße",
        "line_2": " 70",
        "postal_code": "13353",
        "city": "Berlin",
        "country": "DE",
        "state": "BE"
    },
    "email": "theresa@klemm.com",
    "mobile_number": "+49301234567",
    "birth_name": null,
    "birth_date": "1985-12-14",
    "birth_city": "Berlin",
    "birth_country": "DE",
    "nationality": "DE",
    "employment_status": "EMPLOYED",
    "job_title": null,
    "tax_information": {
        "tax_assessment": "SEPARATE",
        "marital_status": "MARRIED"
    },
    "fatca_relevant": false,
    "fatca_crs_confirmed_at": "2022-01-01T00:00:00.000Z",
    "business_purpose": null,
    "industry": "DEBIT_BALANCE_SALARY_ACCOUNT",
    "industry_key": "ECONOMICALLY_DEPENDENT_INDIVIDUALS",
    "terms_conditions_signed_at": "2022-01-01T00:00:00.000Z",
    "own_economic_interest_signed_at": null,
    "aml_follow_up_date": "2029-03-23",
    "aml_confirmed_on": "2022-09-23",
    "flagged_by_compliance": false,
    "expected_monthly_revenue_cents": null,
    "vat_number": null,
    "website_social_media": null,
    "business_trading_name": null,
    "nace_code": null,
    "business_address_line_1": null,
    "business_address_line_2": null,
    "business_postal_code": null,
    "business_city": null,
    "business_country": null,
    "business_state": null,
    "screening_progress": "NOT_SCREENED",
    "risk_classification_status": "NOT_SCORED",
    "customer_vetting_status": "NOT_VETTED",
    "annual_income_range": null,
    "data_terms_signed_at": "2022-01-01T00:00:00.000Z",
    "branch": null,
    "birth_province": null,
    "birth_post_code": null,
    "socioprofessional_category": null,
    "purpose_of_account_opening": null,
    "main_income_source": null,
    "work_country": null,
    "work_province": null,
    "self_declared_as_pep": null,
    "international_operativity_expectation": [],
    "registration_number": null,
    "legitimation_valid_until": null
}

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
attention
  • Fields not mentioned in this list can only be updated via Customer Support.
  • Only for B2C customer: If a customer changes their employment_status to FREELANCER or SELF_EMPLOYED, please note that you must do one of the following options in 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.
  • It's recommended to collect the nace_code from the customer for data quality.

Request URL

Copy
Copied
PATCH /v1/persons/{id}

Click here to view the full API reference


Step 2: Create and verify mobile number

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

Mobile number resource

Creating and verifying a mobile number for your customer is a crucial step in the customer onboarding process. With a verified mobile number, customers can use SMS OTPs to complete two-factor authentication (2FA) challenges, which is a requirement for Strong Customer Authentication (SCA).

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

API reference

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

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:

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

Copy
Copied
{
    "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:

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

Response example:

Copy
Copied
{
    "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:

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

Response example:

Copy
Copied
{
    "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, you must collect the tax information of the customer and create a tax identification resource for them. You can collect the tax information the customer either upon sign-up or within 90 days from opening an account.

What is a tax identification?

As a financial institution, Solaris must comply with various tax regulations, including the Common Reporting Standard (CRS) developed by the Organization for Economic Cooperation and Development (OECD) and the German Steuerumgehungsbekämpfungsgesetz (StUmgBG).

Therefore, Solaris must collect tax information on all individuals and legal entities that are tax residents of a reportable jurisdiction (i.e., a jurisdiction that's obliged under CRS to exchange tax information with other reportable jurisdictions).

The tax information of a person or a business (legal entity), such as tax identification number (TIN) and the tax residency (the country where the customer is taxable) is stored in a tax_identification resource on Solaris's system. There are two types of tax identification resources:

  1. Person tax identification: Used to store the tax information of the following customer types:

    • Retail customers
    • Freelancers or sole proprietors
    • Business legal representatives
    • Business beneficial owners
    • Authorized persons on a business account
    • Authorized persons on a retail account
  2. Business tax identification: Used for a business' legal entity.
attention

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:

  • For customers in Germany (DE branch), you can open the bank account for the customer before providing the tax information. However, you must submit the customer's tax information to Solaris within 90 days of opening the account or otherwise the customer's account will be blocked with the reason MISSING_TAX_INFORMATION until you submit the required tax information.
  • For all other branches apart from DE, you must submit the tax information of the customer from the beginning before an account can be opened.

API reference

Visit the following link to find all the endpoints related to the person tax identification resource, including related properties and examples.

Related webhook events

POST Create person tax identification

This endpoint creates a person tax identification for the customer with the person_id specified in the request URL. To create a tax_identification resource, collect the following tax information from your customers and pass them to Solaris using the following endpoint.

Important
  • 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.
  • A person can only have one tax identification per country.

Mandatory properties:

Add the following properties in the request body of the following endpoint:

  • number: The customer's Tax Identification Number (TIN), issued by the public authorities. Please note:

    • The API automatically validates the number based on the format required for the customer's country. If the supplied TIN does not follow the proper format for the given country, the API will return a 400 error.
    • Check the appendix Tax Identification Number (TIN) by country for details on how to validate the customer's TIN.
  • country: The country where the customer has their tax residence. Uses the two-character ISO 3166-1 alpha-2 codes.
  • primary: Indicates whether this is the customer's primary tax residency. Please note:

    • The first tax_identification to be submitted for a Person 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.
    • Each Person may only have one tax_identification per country.

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: Free text description of why no TIN was provided. Applies only if the reason_no_tin is OTHER.
Important

When creating a tax_identification, always explicitly collect the country value from the user in the frontend. Do not default to the customer's physical residence (i.e., the country property of the person resource).

Request example:

Copy
Copied
POST /v1/persons/{person_id}/tax_identifications
{
  "country": "DE",
  "number": "12345678901",
  "primary": true
}

Response example:

The API returns a tax_identification resource with a unique id.

Copy
Copied
{
  "id": "6d768d88f291f5744f9f30e9c6f2efd4ctin",
  "country": "DE",
  "number": "12345678901",
  "primary": true,
  "reason_no_tin": null,
  "reason_description": null
}

Click here to view the full API reference.

Tax ID validation

Solaris's syntax validation rules for tax IDs enable you to verify your customers' tax identification numbers (TIN) on the spot and reduce wrong entries.

The Solaris API automatically validates the format of the supplied tax identification number (TIN) based on the requirements of the customer's country. If the TIN does not follow the proper format, the API will return a 400 error.

Invalid tax ID 400 error example

Copy
Copied
{
    "errors": [
        {
            "id": "029f7bc9-a4dc-4512-b3ee-65d2eb089804",
            "status": 400,
            "code": "invalid_model",
            "title": "Invalid Model",
            "detail": "number is not a valid person tax identification number for country: ES, for reference please check: https://en.wikipedia.org/wiki/National_identification_number#Spain",
            "source": {
                "field": "number",
                "message": "is not a valid person tax identification number for country: ES, for reference please check: https://en.wikipedia.org/wiki/National_identification_number#Spain"
            }
        }
    ]
}
note

The tax ID validation is only available for person tax identifications, such as retail customers and freelancers, and not businesses. It's activated by default for new customers.

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
info

Check Appendix III for the TIN requirements per country.


Step 4: Create person credit record

In this step, you must create a consumer credit record and link it to the person resource of the relevant customer.

What is a credit record?

The credit record contains the customer's credit data and history. Creating a credit record is usually required in lending products integrations as it's used for credit scoring to determine the customer's creditworthiness and eligibility.

Important
  • The credit record is only valid for onboardings in Germany since the information is retrieved from SCHUFA, which is a German credit bureau.
  • For lending onboardings in other countries, such as France, Italy, and Spain, creating a tax identification for the customer substitutes a credit record.

Integrate the following endpoints to create credit records for your retail customers.

API reference

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

POST Create a credit record for a retail customer

This endpoint creates a credit record for the customer with the person_id specified in the request URL. You can collect this information manually through SCHUFA or other third-party service providers or via Solaris. You must add the following attributes in the request body:

  • source: The source of the file. Possible values are partner or solarisBank.
  • file: The file of the credit record Base64-encoded. Only required If source is set to partner.

Request URL

Copy
Copied
POST /v1/persons/{person_id}/credit_records
{
  "source": "solarisBank",
  "file": null
}

Response example

The API call returns an object with a unique ID, which is the credit_record_id and the status of the credit record, set initially to available.

Copy
Copied
  { 
  "status": "available",
  "person_id": "dc1a6812a14f6cc338cd084208535bcdcper",
  "id": "fbb7d15fa4c54ba0b077592665ef04a4ccrd",
  "created_at": "2020-20-03T18:01:48.000Z"
  }

GET Retrieve a customer's credit record

This endpoint returns the information about a customer's existing credit record, including the status and validity of the credit record. Add the person_id and the credit_record_id in the request URL. If the status of the credit record is expired, you must create a new one for the customer.

Additionally, subscribe to the webhook event PERSON_CREDIT_RECORD to receive notifications when the status of a credit record changes.

Request URL

Copy
Copied
GET /v1/persons/{person_id}/credit_records/{credit_record_id}

Response example

Copy
Copied
  {
  "status": "available",
  "person_id": "dc1a6812a14f6cc338cd084208535bcdcper",
  "id": "fbb7d15fa4c54ba0b077592665ef04a4ccrd",
  "created_at": "2020-20-03T18:01:48.000Z"
  }

Step 5: Create SDD collection application

In this step, you must create a SEPA Direct Debit (SDD) collection application for the customer. This application is created in the context of onboarding customers for decoupled cards, and it automatically triggers the consumer decoupled cards scorer.

The scorer evaluates the application's data and the applicant's credit risk to determine their eligibility for a decoupled card and the credit limit to be granted.

POST Create SDD collection application

Important

A credit record is a prerequisite for creating an SDD collection application. Before calling this endpoint, you must complete Step 4: Create person credit record.

This endpoint creates an SDD collection application and assigns it to the person with the person_id specified in the request URL. In addition, you must include the credit_record_id you created in the previous step in the request body.

Request URL

Copy
Copied
POST /persons/{person_id}/sdd_collection_applications
{
  "credit_record_id": "fbb7d15fa4c54ba0b077592665ef04a4ccrd"
}

Response example

The API will return an object containing a unique ID for the SDD collection application as well as the application's status, which is initially set to initial_scoring_pending. You must use this id in later API calls as the value of sdd_collection_application_id.

This call triggers the credit scoring system, which runs credit checks on the customer based on the credit record and the application data. The credit scoring result determines the decision field, which is Solaris' decision on the SDD collection application on whether a decoupled card can be offered to the customer or not. The decision can either be OFFERED or REJECTED.

Copy
Copied
{
    "id": "85a44f6e74cdfa8638a59f18e7b9b276DCA",
    "person_id": "d96ec42caa105b417d7fbc07a7d365c2cper",
    "credit_record_id": "6ac0ced18b9f4f4580e60bc8a4b2ffcbccrd",
    "sdd_collection_id": null,
    "account_snapshot_id": null,
    "status": "account_snapshot_pending",
    "decision": "OFFERED",
    "limit": null,
    "rejection_reasons": [],
    "created_at": "2020-10-08T09:53:26.000+00:00"
}

Click here to view the full API reference.

GET Retrieve customer SDD collection application

This endpoint retrieves a customer's SDD collection application. You can use this endpoint to track the application lifecycle through the status field in the response body. Alternatively, subscribe to the webhook event SDD_COLLECTION_APPLICATION to receive notifications whenever the application status changes.

Check the appendix for a list of possible values and descriptions for the status field.

Request URL

Copy
Copied
GET /persons/{person_id}/sdd_collection_applications/{sdd_collection_application_id}

Click here to view the full API reference.


Step 6: Create account snapshot

In this step, you must create an account snapshot for the customer and link it to their SDD collection application. Complete this step when the application status changes to account_snapshot_pending.

What is an account snapshot?

The account snapshot contains a breakdown of the customer's account information, such as balance, transactions, bookings, and recurrent repayment amounts over a certain period of time. Creating an account snapshot is usually required in lending products integrations as it's used for credit scoring to verify the customer's financial data.

Integrate the following endpoints to create account snapshots for your customers.

API reference

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

POST Create an account snapshot for a customer

This endpoint creates an account snapshot for the customer with the person_id specified in the request URL. You can create an account snapshot in different ways by specifying the source of the account snapshot.

1. Account snapshot via FinTech systems

You can create an account snapshot via FIN_TECH_SYSTEMS by completing the following steps:

  1. Integrate the FIN_TECH_SYSTEMS wizard container in your solution by following their documentation.
  2. Call the following endpoint and add the following properties in the request body:

    • source: FIN_TECH_SYSTEMS
    • iban: (Optional) you can add the IBAN of the customer's account.
  3. The API call will return a wizard_session_key, which you must enter in the FIN_TECH_SYSTEMS wizard container to start the account snapshot session.
  4. The customer enters their bank credentials to initiate the account snapshot.

Request example

Copy
Copied
POST /v1/persons/{person_id}/account_snapshots
{
    "source": "FIN_TECH_SYSTEMS"
}

Response example

The API call returns a resource with a unique ID, the account_snapshot_id, as well as the wizard_session_key.

Copy
Copied
{
    "wizard_session_key": "Hm7jUSC7XU2nQjPqJO8dl39eDkdjtOdCtywcmv3x",
    "location": null,
    "id": "8df2a8ba713c43dc9cb481b9cceed487snap",
    "account_id": null
}

2. Account snapshot via Finreach

You can create an account snapshot via FinX by completing the following steps:

  1. Integrate the FinX widget in your solution by following their documentation.
  2. Call the following endpoint and add the following properties in the request body:

    • source: FINREACH
  3. The API call will return a location, which is a URL to which you must redirect your customer to enter their bank credentials to initiate the account snapshot.

Request example

Copy
Copied
POST /v1/persons/{person_id}/account_snapshots
{
  "source": "FINREACH"
}

Response example

The API call returns a resource with a unique ID, the account_snapshot_id, as well as URL to which you must redirect the customer.

Copy
Copied
{
    "wizard_session_key": null,
    "location": "https://ui.solaris-i.prod.finleap.cloud?token=xxxxxx",
    "id": "8df2a8ba713c43dc9cb481b9cceed487snap",
    "account_id": null
}

3. Account snapshot via partner

If you want to upload the details of an account snapshot you've created (e.g., if you already have your own connection with FIN_TECH_SYSTEMS or FINREACH), specify the source of the account snapshot file as partner and add the account snapshot data in the snapshot_data field.

Request example

Copy
Copied
POST /v1/persons/{person_id}/account_snapshots
{
    "source": "PARTNER",
    "snapshot_data": {
    "account": {
        "bank_name": "",
        "bic": "",
        "country_id": "",
        "description": "",
        "holder": "John Smith",
        "iban": "DE92370601930002130041",
        "joint_account": false
    },
    "balance": {
        "balance": 3720.20,
        "currency": "EUR",
        "date": "2022-02-03",
        "limit": 0
    },
    "date": "2022-02-03",
    "days": 90,
    "turnovers": [
        {
            "amount": 4000.05,
            "booking_date": "2022-02-01",
            "counter_bic": "",
            "counter_holder": "Salary company",
            "counter_iban": "DE89500105177323343587",
            "currency": "EUR",
            "purpose": [
                "LOHN / GEHALT 01/22"
            ],
            "tags": [],
            "CrifCategory": "RE_05"
        },
        {
            "amount": 4000.05,
            "booking_date": "2022-01-02",
            "counter_bic": "",
            "counter_holder": "Salary company",
            "counter_iban": "DE89500105177323343587",
            "currency": "EUR",
            "purpose": [
                "LOHN / GEHALT 12/21"
            ],
            "tags": [],
            "CrifCategory": "RE_05"
        },
        {
            "amount": 4000.05,
            "booking_date": "2021-12-01",
            "counter_bic": "",
            "counter_holder": "Salary company",
            "counter_iban": "DE89500105177323343587",
            "currency": "EUR",
            "purpose": [
                "LOHN / GEHALT 11/21"
            ],
            "tags": [],
            "CrifCategory": "RE_05"
        },
              {
            "amount": 4000.05,
            "booking_date": "2021-11-05",
            "counter_bic": "",
            "counter_holder": "Salary company",
            "counter_iban": "DE89500105177323343587",
            "currency": "EUR",
            "purpose": [
                "LOHN / GEHALT 10/21"
            ],
            "tags": [],
            "CrifCategory": "RE_05"
        }
    ]
}
}

Response example

The API call returns a resource with a unique ID, the account_snapshot_id.

Copy
Copied
{
  "wizard_session_key": null,
  "location": null,
  "id": "0a3f28733f9a4842842aae2804f80eb4snap",
  "account_id": null
}

4. Account snapshot via Solaris

You can create an account snapshot via Solaris for internal accounts by specifying the source as SOLARISBANK and adding the customer's account_id in the request body.

Request example

Copy
Copied
{
  "source": "SOLARISBANK",
  "account_id": "adc123a45d6d7cf8fbfeed537ba919d5cacc"
}

Response example

The API call returns a resource with a unique ID, the account_snapshot_id.

Copy
Copied
POST /v1/persons/{person_id}/account_snapshots
{
  "wizard_session_key": null,
  "location": null,
  "id": "0a3f28733f9a4842842aae2804f80eb4snap",
  "account_id": "adc123a45d6d7cf8fbfeed537ba919d5cacc"
}

GET Retrieve a customer's account snapshot

This endpoint returns the information about a customer's existing account snapshot, including the status and validity of the account snapshot. Add the person_id and the account_snapshot_id in the request URL. If the status of the account snapshot is expired, you must create a new one for the customer.

Additionally, subscribe to the webhook event ACCOUNT_SNAPSHOT to receive notifications when the status of an account snapshot changes.

Request URL

Copy
Copied
GET /v1/persons/{person_id}/account_snapshots/{account_snapshot_id}
attention

If you are using Bankident to identify the customer, the account snapshot is automatically created within the payment verification step. Check the Bankident guide for more details.

PUT Link customer account snapshot to SDD collection application

This endpoint attaches the account snapshot created for the customer to their existing SDD collection application. You must add the account_snapshot_id to the request body.

Once linked, the application status will change to account_snapshot_verification_pending. Calling this endpoint also sends a webhook notification on the SDD_COLLECTION_APPLICATION event.

Additionally, this action triggers the credit scoring system to perform the final verification step on the customer's bank account to determine the overdraft limit based on the customer's income, expenses, and recurring credit repayments. After successful verification, the application status changes to offered.

Request URL

Copy
Copied
PUT /persons/{person_id}/sdd_collection_applications/{sdd_collection_application_id}/account_snapshot
{
  "account_snapshot_id": "0a3f28733f9a4842842aae2804f80eb4snap"
}

Click here to view the full API reference.


Step 7: Complete the customer identification and due diligence process

In this step, you must complete the Know Your Customer (KYC) process successfully and the customer due diligence process.

Customer identification

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

In this step, you must create the customer identification resource and trigger the identification process for your customer.

Solaris offers different identification methods based on the product, region, and customer type. For an overview of available KYC methods, check the customer KYC products overview page.

You can use the following identification methods to identify customers for decoupled cards:

attention
  • The previous links will take you to the integration guide of each identification method. Go to the integration guide of your chosen identification method and complete the steps to identify your customer.
  • Please skip the preparation/setup steps in the identification guides, as they have already been covered here in this guide.

Customer due diligence

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

Check the related guide for more information.


Step 8: Set up customer internal account

Important prerequisites

In this step, you must create the internal account for the customer and attach the approved credit limit. Then, when the customer uses their decoupled card to make a purchase, the balance of this account will go negative, and the customer's external reference account will be debited in the amount of the negative balance. The SDD will be credited to this account for settlement.

The customer can top up this account and transfer any positive balance back to the reference account.

IMPORTANT

The internal account is not a full payments bank account and can only be used within the constraints of the decoupled card.

POST Create internal account

This endpoint creates an account for the customer with the person_id specified in the request URL. You must add the account type to the request body as DECOUPLED_CARD_PERSONAL.

Request URL

Copy
Copied
POST /v1/persons/{person_id}/accounts
{
    "type": "DECOUPLED_CARD_PERSONAL"
}

Response example

The API call returns an object with a unique ID, which is the account_id, as well as the account IBAN, limit, and balance.

Copy
Copied
Created 201
{
    "id": "cb752d28214bcfea4c285de600ad0105cacc",
    "iban": "DE54110101002897397718",
    "bic": "SOBKDEBBXXX",
    "type": "DECOUPLED_CARD_PERSONAL",
    "balance": {
        "value": 0,
        "unit": "cents",
        "currency": "EUR"
    },
    "available_balance": {
        "value": 0,
        "unit": "cents",
        "currency": "EUR"
    },
    "locking_status": "NO_BLOCK",
    "locking_reasons": [],
    "account_limit": {
        "value": 0,
        "unit": "cents",
        "currency": "EUR"
    },
    "person_id": "6028c17554ecf6d71cda357d536835e4cper"
}

Click here to view the full API reference.

PUT Link internal account to SDD collection application

This endpoint attaches the created internal account to the SDD collection application. You must add the account_id returned from the previous call in the request body.

Request URL

Copy
Copied
PUT /persons/{person_id}/sdd_collection_applications/{sdd_collection_application_id}/account
{
  "account_id": "cb752d28214bcfea4c285de600ad0105cacc"
}

Click here to view the full API reference.

Afterward, Solaris will attach the credit limit to the account, which the customer can use via the decoupled card.


Step 9: Create reference account and SDD mandate

In this step, you must create an SDD mandate and store it in the reference account resource.

What is the SDD mandate, and how do you create it?

The SEPA Direct Debit (SDD) mandate is the customer's authorization for Solaris to collect funds from their account in the future. You must create this mandate and collect the customer's signature for the mandate and the terms and conditions.

You must generate a unique SDD mandate number. The mandate_number must contain 35 characters, and the first 6 must be RCIAIR. The remaining 29 may only contain the following: [A-Z], [a-z], [0-9].

You must display the following information to the customer before they sign the mandate:

  • Full name (First_name + last_name)
  • IBAN (this should be retrieved from the account snapshot)
  • Generated mandate reference
  • Name of Payee: Solarisbank AG
  • Legal text containing an authorization for the mandate

POST Create reference account

After creating the SDD mandate, you must create a reference account resource for the customer and link it to the internal account. You must add the customer's person_id and account_id in the request URL. You must add the external account details and the signed mandate information in the request body.

You must include the following properties in the request body:

  • name: The customer's name on their external bank account.
  • iban: The IBAN of the external bank account from which the SDD will be debited.
  • mandate_number: The number of the SDD mandate the customer signed.
  • mandate_signature_date: The date when the customer signed the SDD mandate.

Request URL

Copy
Copied
// POST /v1/persons/{person_id}/accounts/{account_id}/reference_accounts
{
 	"name": "Max Mustermann",
  "iban": "DE32110101001000000029",
 	"mandate_number": "SAMPAY7D226d32882d11Eb8DcD0242Ae2F4",
 	"mandate_signature_date": "2016-04-20"
}

Response example

The API call returns an object with a unique ID, which is the reference account ID. The status field refers to the reference account's status. Possible values are ACTIVE and INACTIVE.

Copy
Copied
{ 
  "id": "1231231239ref",
  "status": "ACTIVE",
  "name": "Max Mustermann",
  "iban": "DE32110101001000000029",
  "mandate_number": "SAMPAY7D226d32882d11Eb8DcD0242Ae2F4",
  "mandate_signature_date": "2016-04-20"
}

Click here to view the full API reference.

GET Index reference accounts for a person

This endpoint retrieves the reference accounts associated with a specific person's account. You must include the customer's person_id and the account_id of their internal Solaris account in the request URL.

Request URL

Copy
Copied
GET /v1/persons/{person_id}/accounts/{account_id}/reference_accounts

Click here to view the full API reference.


Step 10: Create and activate decoupled card

After creating the relevant accounts, the final step is to create and activate the decoupled card. 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.

For step-by-step instructions on issuing, activating, and servicing cards, check the dedicated card servicing guide.


Servicing decoupled cards

This section includes information about actions customers may take after receiving their decoupled card. Customers can request the following:

  • Change the reference account
  • Request a change on the credit limit available on the card
  • Disable the credit limit available on the card
  • Issue payouts to the reference account. Only in the case of having positive balance.

Change the reference account

If the customer wants to change the reference account associated with the SDD collection, please repeat Step 9: Create reference account and SDD mandate. Please be aware that you must create a new SDD mandate for the new reference account and collect the customer's signature on it.

attention

Once you create a new reference account for the customer, the status of the previous reference account automatically changes to INACTIVE.

Change the SDD collection limit

Customers can request an SDD collection limit change or disable the SDD collection limit entirely from the account. Implement the following endpoints in your solution to do so.

POST Create an SDD collection limit on the customer account

This endpoint creates a new SDD collection limit and attaches it to the account specified in the request URL. You must add the following properties to the request body:

  • limit: The amount of the credit limit to be attached to the account in EURO.
  • limit_type: The type of SDD collection limit. Use CUSTOMER_REQUEST.

Request URL

Copy
Copied
POST /persons/{person_id}/accounts/{account_id}/sdd_collection_limits

Response example

Copy
Copied
{
  "comment": "Comment",
  "limit": {
    "value": 100,
    "unit": "cents",
    "currency": "EUR"
  },
  "limit_type": "CUSTOMER_REQUEST"
}

Click here to view the full API reference.

DELETE Disable the SDD collection limit on the customer account

This endpoint disables the active SDD collection limit from the customer's account specified in the request URL. You must add the following properties to the request body:

  • limit_type: The type of SDD collection limit. Value is CUSTOMER_REQUEST.

Request URL

Copy
Copied
DELETE /persons/{person_id}/accounts/{account_id}/sdd_collection_limits

Click here to view the full API reference.

Issue payouts to reference account

If the customer tops up the balance on the internal account associated with their decoupled card to a positive value, they can transfer the positive balance back to their reference account. To do so, implement the following endpoints in your solution:

Important
  • Payouts only work if the account has a positive balance and may only be made to the reference account(s) associated with the decoupled card.
  • Customers cannot transfer money from the cards's credit limit to the reference account or make a transfer to other bank accounts.

POST Initiate a payout to a specific reference account

This endpoint initiates a payout to a reference account associated with a specific customer. In the request URL, you must include the customer's person_id, the account_id (of the internal account), and the reference_account_id. In the request body, you must include the following properties:

  • reference: A field to add your unique reference for the transaction.
  • end_to_end_id: Your unique identifier for the transaction, which will be routed throughout the whole payment process.
  • amount: The payout amount, including value, unit, and currency.
  • description: Field to add additional description for the transaction.

Request URL

Copy
Copied
POST /v1/persons/{person_id}/accounts/{account_id}/reference_accounts/{reference_account_id}/payouts

Response example

The API call returns an object with a unique ID for the payout and the status of the payout, which can be accepted, executed, or declined. Once the payout is executed, a new booking will be created on the account and a BOOKING webhook notification will be sent.

Copy
Copied
{
  "id": "12312312312pyo",
  "reference": "unique_partner_reference",
  "status": "accepted",
  "amount": {
    "value": 10000,
    "unit": "cents",
    "currency": "EUR",
  },
  "end_to_end_id": "123123123",
  "reference_account_id": "1231231239ref",
  "description": "Withdrawl SPAY - DD.MM.YYYY"
}

Click here to view the full API reference.

GET Retrieve a single reference account payout

This endpoint retrieves the details of a specific payout made to a reference account. You must add the payout id in the request URL.

Request URL

Copy
Copied
GET /v1/persons/{person_id}/accounts/{account_id}/reference_account_payouts/{id}

Click here to view the full API reference.


What's next?

Congratulations! You've successfully integrated Solaris' Decoupled Cards product.

Check the following mandatory features section to find the links to the additional features you must implement in your solution. Additionally, the appendix section includes additional information on enums and testing data.

Mandatory features

You must implement the following additional mandatory features in your solution.

Compliance requirements

Authentication & authorization

Digital Banking & Cards


Appendix I: Enums

SDD collection application status

The following table includes the possible values for the SDD collection application status field and their descriptions.

Status Description
initial_scoring_pending The application has been created, and the credit scoring system has been triggered to perform the initial credit checks on the customer.
account_snapshot_pending You must create an account snapshot for the customer and attach it to the application for the final verification step required by the credit scoring system.
account_snapshot_verification_pending The account snapshot has been attached to the application, and the credit scoring system has been triggered to perform the final verification step.
rejected The SDD collection application has been rejected, as it did not pass the credit checks.
offered The SDD collection application has been approved, and a limit has been offered to the customer based on the credit score.
overdraft_created The overdraft credit limit has been created on the customer's account.

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_COMPACT_REPORT A compact SCHUFA report.
SCHUFA_GWG_REPORT A GWG 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 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

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_successful The video identification was successful, but will be reviewed by the identification provider. You can already offer banking services to the customer at this stage. Once reviewed by the provider, the identification will be marked either as resolved positively (successful) or negatively (failed or canceled). A bank account will be automatically blocked if the identification is eventually marked as failed or canceled.
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 for the canceled and aborted status. No reason can be disclosed for the final failed status.

Identification documents

  1. List of the accepted passports for videoIdent: here
  2. List of accepted passports for postIdent: here
  3. Search for a identification document: here

List of passports with address

The following table shows the list of documents, that has the address included in the identification document, and allows you to perform identification without the proof of address document.

Document Issuer Country Type (ID/PP)
MLT-BO-02001 Malta ID
MLT-BO-03001 Malta ID
SVK-BO-02001 Slovakia ID
SVK-BO-05001 Slovakia ID
SVK-BO-04001 Slovakia ID
ITA-BO-04003 Italy ID
ITA-BO-03004 Italy ID
ITA-BO-03002 Italy ID
ITA-BO-03001 Italy ID
ITA-BO-03003 Italy ID
DEU-BO-01003 Germany ID
DEU-BO-02001 Germany ID
SGP-BO-01001-A Singapore ID
SGP-BO-01001 Singapore ID
CZE-BO-04001 Czech Republic ID
CZE-BO-04002 Czech Republic ID
IND-AO-01001 India Passport
CHN-AO-04003 China Passport
BGR-AO-01005 Bulgaria Passport
SVN-AO-02001-02003 Slovenia Passport
SVN-AO-02004 Slovenia Passport
SVN-BO-02001 Slovenia ID
SVN-AO-01004 Slovenia Passport
POL-BO-02001-02003 Poland ID
ESP-BO-03001 Spain ID
ESP-BO-05001 Spain ID
HRV-BO-02001 Croatia ID
HRV-AO-02001 Croatia Passport
FRA-BO-02002 France ID
FRA-AO-03001-03003 France Passport
MAR-AO-02001 Morocco Passport

Appendix II: Required data points by country

France

  • salutation

    • Note: MR for male, MS for female; no gender-neutral options allowed.
  • first_name
  • last_name
  • branch

    • Note: Must be FR.
  • address

    • line_1
    • line_2
    • postal_code
    • city
    • country (Note: only France is allowed)
  • contact_address

    • line_1
    • line_2
    • postal_code
    • city
    • country (Note: only France is allowed)
  • email
  • birth_name
  • birth_date
  • birth_city
  • birth_country

    • Note: Same type as country.
  • (Lending products only)birth_province: A 2-digit alphanumeric code that indicates the département where the customer was born. See the following table for a list of INSEE codes and use the mapped values in the right column as the values for this property.
  • birth_post_code

    • Note: Only required for customers born in France. Use the two- or three-digit code corresponding with the département de naissance where the customer was born.
  • nationality
  • employment_status (enumeration, possible values below):

    • EMPLOYED
    • SELF_EMPLOYED
    • UNEMPLOYED
    • RETIRED
    • STUDENT
    • Note: If the customer selects the options EMPLOYED or SELF_EMPLOYED, then the nace_code, socioprofessional_category and work_country parameters should be made available.
  • nace_code

  • work_country

    • Note: Same type as country.
  • job_title
  • socioprofessional_category (enumeration, possible values below):

    • FARMERS
    • CRAFTSMEN
    • MERCHANTS_AND_COMPANY_MANAGERS
    • MANAGERS_AND_HIGHER_INTELLECTUAL_PROFESSIONS
    • INTERMEDIATE_PROFESSIONS
    • EMPLOYEES
    • WORKERS
  • purpose_of_account_opening (enumeration, possible values below)

    • SAVINGS
    • DAILY_EXPENSES
    • TRAVELLING_AND_RELOCATING
    • FREELANCER_ACTIVITY
    • ONLINE_SHOPPING
    • SALARY_OR_PENSION_ACCREDITATION
    • TRADING
  • main_income_source (enumeration, possible values below)

    • SALARY_INCOME_OR_OWN_BUSINESS
    • REAL_ESTATE_INCOME
    • INCOME_FROM_SAVINGS
    • SALES_OF_ASSETS
    • FAMILY_INCOME
    • DONATIONS
    • INHERITANCE
    • PENSION
    • PUBLIC_SUBSIDIES
  • annual_income_range (abstract enumeration, see the table below for descriptions of the ranges)

    • RANGE_1
    • RANGE_2
    • RANGE_3
    • RANGE_4
    • RANGE_5
    • RANGE_6
    • RANGE_7
  • fatca_relevant
  • fatca_crs_confirmed_at
  • terms_conditions_signed_at
  • own_economic_interest_signed_at
  • tax_information

    • tax_assessment (single or shared account, possible values below:)

      • NONE
      • SEPARATE
      • JOINT

French province codes

This table maps the INSEE code of each French province with the name to display to your customers in a drop-down menu as well as the value to assign to the birth_province property of the Person.

code_departement (INSEE code) nom_departement (Dropdown menu for customers) birth_province (value to send to the Solaris API)
1 Ain 01
2 Aisne 02
3 Allier 03
4 Alpes-de-Haute-Provence 04
5 Hautes-Alpes 05
6 Alpes-Maritimes 06
7 Ardèche 07
8 Ardennes 08
9 Ariège 09
10 Aube 10
11 Aude 11
12 Aveyron 12
13 Bouches-du-Rhône 13
14 Calvados 14
15 Cantal 15
16 Charente 16
17 Charente-Maritime 17
18 Cher 18
19 Corrèze 19
21 Côte-d'Or 21
22 Côtes-d'Armor 22
23 Creuse 23
24 Dordogne 24
25 Doubs 25
26 Drôme 26
27 Eure 27
28 Eure-et-Loir 28
29 Finistère 29
2A Corse-du-Sud 2A
2B Haute-Corse 2B
30 Gard 30
31 Haute-Garonne 31
32 Gers 32
33 Gironde 33
34 Hérault 34
35 Ille-et-Vilaine 35
36 Indre 36
37 Indre-et-Loire 37
38 Isère 38
39 Jura 39
40 Landes 40
41 Loir-et-Cher 41
42 Loire 42
43 Haute-Loire 43
44 Loire-Atlantique 44
45 Loiret 45
46 Lot 46
47 Lot-et-Garonne 47
48 Lozère 48
49 Maine-et-Loire 49
50 Manche 50
51 Marne 51
52 Haute-Marne 52
53 Mayenne 53
54 Meurthe-et-Moselle 54
55 Meuse 55
56 Morbihan 56
57 Moselle 57
58 Nièvre 58
59 Nord 59
60 Oise 60
61 Orne 61
62 Pas-de-Calais 62
63 Puy-de-Dôme 63
64 Pyrénées-Atlantiques 64
65 Hautes-Pyrénées 65
66 Pyrénées-Orientales 66
67 Bas-Rhin 67
68 Haut-Rhin 68
69 Rhône 69
70 Haute-Saône 70
71 Saône-et-Loire 71
72 Sarthe 72
73 Savoie 73
74 Haute-Savoie 74
75 Paris 75
76 Seine-Maritime 76
77 Seine-et-Marne 77
78 Yvelines 78
79 Deux-Sèvres 79
80 Somme 80
81 Tarn 81
82 Tarn-et-Garonne 82
83 Var 83
84 Vaucluse 84
85 Vendée 85
86 Vienne 86
87 Haute-Vienne 87
88 Vosges 88
89 Yonne 89
90 Territoire de Belfort 90
91 Essonne 91
92 Hauts-de-Seine 92
93 Seine-Saint-Denis 93
94 Val-de-Marne 94
95 Val-d'Oise 95
971 Guadeloupe 97
972 Martinique 97
973 Guyane 97
974 La Réunion 97
976 Mayotte 97
99 Other (for customers not born in France or a French overseas department) 99

Germany

  • salutation

    • Note: MR for male, MS for female, null for gender-neutral.
  • first_name
  • last_name
  • address

    • line_1
    • line_2
    • postal_code
    • city
    • country
  • mobile_number
  • birth_date
  • birth_city
  • birth_country
  • nationality
  • employment_status (enumeration, possible values below):

    • EMPLOYED
    • UNEMPLOYED
    • PUBLIC_SECTOR_EMPLOYEE
    • PROFESSIONAL_SOLDIER
    • FREELANCER
    • HOUSEWORK
    • APPRENTICE
    • MANAGEMENT
    • RETIRED
    • STUDENT
    • SELF_EMPLOYED
    • MILITARY_OR_COMMUNITY_SERVICE
  • work_country

    • Note: Same type as country.
  • fatca_relevant
  • fatca_crs_confirmed_at
  • terms_conditions_signed_at
  • own_economic_interest_signed_at
  • tax_information

    • tax_assessment (single or shared account, possible values below:)

      • NONE
      • SEPARATE
      • JOINT

Italy

  • salutation

    • Note: MR for male, MS for female; no gender-neutral options allowed.
  • first_name
  • last_name
  • branch

    • Note: Must be IT.
  • address (Italian: residenza): The customer's legal residence. Must contain the street name and house number.

  • contact_address (Italian: domicilio): The customer's temporary residence or formally registered secondary address, i.e., not a random shipping address. Must contain the street name and house number.

  • email
  • birth_date
  • birth_city
  • birth_country: 2-digit ISO 3166-2 code.
  • birth_province: 2-digit Italian province code. Click here for a full list of province codes.

    • Note: If the customer's birth_country is NOT IT, then the value must be set to EE.
  • nationality
  • employment_status: Note that these are the only possible values for Italy:

    • EMPLOYED
    • SELF_EMPLOYED
    • STUDENT
    • RETIRED
    • UNEMPLOYED
    • Note: If the customer selects the options EMPLOYED or SELF_EMPLOYED, then the nace_code and work_country parameters should be made available.
  • nace_code (relevant NACE (ATECO) code limited to the 3rd level).

    • Note: Only applies to customers with an employment_status of EMPLOYED or SELF_EMPLOYED.
  • work_country: 2-digit ISO 3166-2 code.
  • work_province: (Only provide if the work_country is IT) 2-digit Italian province code. Click here for a full list of province codes.
  • purpose_of_account_opening (enumeration, possible values below)

    • SAVINGS
    • DAILY_EXPENSES
    • TRAVELLING_AND_RELOCATING
    • FREELANCER_ACTIVITY
    • ONLINE_SHOPPING
    • SALARY_OR_PENSION_ACCREDITATION
    • TRADING
  • main_income_source (enumeration, possible values below)

    • SALARY_INCOME_OR_OWN_BUSINESS
    • REAL_ESTATE_INCOME
    • INCOME_FROM_SAVINGS
    • SALES_OF_ASSETS
    • FAMILY_INCOME
    • DONATIONS
    • INHERITANCE
    • PENSION
    • PUBLIC_SUBSIDIES
  • annual_income_range (abstract enumeration, see the table below for descriptions of the ranges)

    • RANGE_1
    • RANGE_2
    • RANGE_3
    • RANGE_4
    • RANGE_5
    • RANGE_6
    • RANGE_7
  • fatca_relevant
  • fatca_crs_confirmed_at
  • self_declared_as_pep (boolean)
  • terms_conditions_signed_at
  • own_economic_interest_signed_at

Spain

  • first_name

    • Note: Must include all first names, separated by spaces.
  • last_name

    • Note: Must include first and second last names, separated by spaces.
  • branch

    • Note: Must be ES.
  • address

  • email
  • birth_date
  • birth_city
  • birth_country: 2-digit ISO 3166-2 code.
  • birth_province: 2-digit Spanish province code. Click here for a full list of Spanish province codes.
  • nationality
  • employment_status
  • work_country: 2-digit ISO 3166-2 code.
  • work_province (Only provide if work_country is ES) 2-digit Spanish province code. Click here for a full list of Spanish province codes.
  • purpose_of_account_opening (enumeration, possible values below)

    • SAVINGS
    • DAILY_EXPENSES
    • TRAVELLING_AND_RELOCATING
    • FREELANCER_ACTIVITY
    • ONLINE_SHOPPING
    • SALARY_OR_PENSION_ACCREDITATION
    • TRADING
  • main_income_source (enumeration, possible values below)

    • SALARY_INCOME_OR_OWN_BUSINESS
    • REAL_ESTATE_INCOME
    • INCOME_FROM_SAVINGS
    • SALES_OF_ASSETS
    • FAMILY_INCOME
    • DONATIONS
    • INHERITANCE
    • PENSION
    • PUBLIC_SUBSIDIES
  • annual_income_range (abstract enumeration—see the following table for descriptions of the ranges)

    • RANGE_1
    • RANGE_2
    • RANGE_3
    • RANGE_4
    • RANGE_5
    • RANGE_6
    • RANGE_7
  • fatca_relevant
  • fatca_crs_confirmed_at
  • terms_conditions_signed_at
  • own_economic_interest_signed_at

Appendix III: Tax Identification Number (TIN) by country

France TIN

In France, the TIN is 15 digits long, and the last two digits are letters.

Italy TIN

The Italian equivalent of the TIN is the codice fiscale. It is calculated by a legally established algorithm and must be verified by your frontend implementation.

Codice fiscale validation

Please refer to the decree of the Finance Ministry for the source of this algorithm.

Example: RSSMRA99D20F205R

Position 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
Digit R S S M R A 9 9 D 2 0 F 2 0 5 R
Position in fiscal code Meaning of digits How it is computed
1-3 Last name Last names composed of multiple parts are always considered as a continuous sequence of characters; For women, this is always the maiden name; If the surname has three or more consonants, then the first, second, and third consonants are used; If the surname has two consonants, then the first and second consonants and first vowel are used; If the surname has one consonant and two vowels, then the first consonant and then the first and second vowels are used; If the surname has one consonant and one vowel, then the first consonant is used, then the first vowel, then "x"; If the surname has only two vowels, then the first and second vowel are used, followed by "x".
4-6 First name Last names composed of multiple parts are always considered as a continuous sequence of characters; If the first name has three or more consonants, then the first, second, and third consonants are used; If the first name has two consonants, then the first and second consonants and the first vowel are used; If the first name has one consonant and two vowels, then the first consonant and the first and second vowels are usedd; If the first name has one consonant and one vowel, then the first consonant and first vowel are used, followed by "x"; If the first name has only two vowels, then the first and second vowel are used, followed by "x".
7-8 Year of birth Last two digits of the birth year (e.g., for customers born in 1975, these digits would be 75).
9 Month of birth The month is assigned a letter based on the rules described in table 4 (e.g., if a person is born in June, this digit would contain the letter H).
10-11 Day of birth & gender These two digits are computed based on the gender. For male persons: the digits correspond with the exact date of birth (01 to 31); For female persons: the digits correspond with the exact date of birth + 40, so value is from 41 to 71. E.g., if a female person is born on the 10th day in the month, then these two digits would be 50. The birth month assigned a letter based on the rules described in table 4 (e.g., if a person is born in June, this digit would contain the letter H).
12-15 Place of birth These digits consist of one letter and three numbers. For persons in Italy, then they represent the town and province of birth; For persons outside of Italy, then they represent the country of birth.
16 Control character The digits at the even positions are converted to the values listed in Table 1; The digits at the odd positions are converted to the values listed in Table 2; The resulting numbers are summed and divided by 26; Then, this resulting number is converted to the letter that corresponds with its numeric value, as described in Table 3.
Duplicates In the event that the first 15 digits of an existing codice fiscale would be the same for two or more persons, there is a method to avoid creating a duplicate codice fiscale once it has been registered. The first number of the codice fiscale starting from the right is converted to a letter as described in Table 5. E.g., for the second person with same codice fiscale, the first number from the right is converted to a letter; for the third person with the same codice fiscale, the first and second numbers from the right are converted to letters.

Table 1

Character Value Character Value Character Value Character Value
0 0 9 9 I 8 R 17
1 1 A 0 J 9 S 18
2 2 B 1 K 10 T 19
3 3 C 2 L 11 U 20
4 4 D 3 M 12 V 21
5 5 E 4 N 13 W 22
6 6 F 5 O 14 X 23
7 7 G 6 P 15 Y 24
8 8 H 7 Q 16 Z 25

Table 2

Character Value Character Value Character Value Character Value
0 1 9 21 I 19 R 8
1 0 A 1 J 21 S 12
2 5 B 0 K 2 T 14
3 7 C 5 L 4 U 16
4 9 D 7 M 18 V 10
5 13 E 9 N 20 W 22
6 15 F 13 O 11 X 25
7 17 G 15 P 3 Y 24
8 19 H 17 Q 6 Z 23

Table 3

Character Value Character Value Character Value Character Value
0 A 7 H 14 O 21 V
1 B 8 I 15 P 22 W
2 C 9 J 16 Q 23 X
3 D 10 K 17 R 24 Y
4 E 11 L 18 S 25 Z
5 F 12 M 19 T
6 G 13 N 20 U

Table 4

Month Value Month Value Month Value Month Value
January A April D July L October R
February B May E August M November S
March C June H September P December T

Table 5

Character Value Character Value Character Value Character Value
0 L 3 P 6 S 9 V
1 M 4 Q 7 T
2 N 5 R 8 U

Spain TIN

The Spanish equivalent of a TIN is the NIF (Número de Identificación Fiscal).

  • for Spanish citizens, the TIN value is the same as the National ID (DNI - Documento Nacional de Identidad) and contains 8 digits and 1 letter.
  • for non-citizens in Spain, the TIN value is the same as Foreigner ID (NIE - Número de Identidad/Identificación de Extranjero) and contains 7 digits and two letters (1 letter at the beginning and 1 letter at the end).