Onboard a person (Digital Banking & Cards)

This guide describes how to onboard new retail customers (persons) in your banking solution for Digital Banking and Cards products using Solaris’s Digital Banking API. It includes step-by-step instructions for each phase of the onboarding process, including the mandatory information you must collect from your customers and the necessary endpoints and webhooks you must integrate into your solution.

Introduction

User journey

A customer can open a bank account by completing the following steps on your frontend:

  1. Consent to the legal and regulatory requirements, such as Solaris' terms and conditions, FATCA relevance, and data terms.
  2. Enter the required personal information.
  3. Enter and verify their mobile number.
  4. Complete the video identification process with IDnow.
  5. Request opening a bank account.
  6. Order and activate the card.
  7. Provide their tax information either upon sign-up or within 90 days from opening the account.

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

The following sequence diagram gives an overview of the integration flow for onboarding retail customers for Digital Banking Cards:

Diagram: Person onboarding flow

Integration steps

Onboard retail customers by completing the following 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. Create a person tax identification by completing Step 3.

Customer identification and due diligence

  1. Create an identification resource for the customer and specify the identification method by completing Step 4.
  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.

Account and card setup

  1. Create an account for the customer by completing Step 5.
  2. Create and activate the debit card for the customer by completing Step 6.

Mandatory features

You must integrate all the mandatory features highlighted in this section.

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). Creating a person resource is typically the first step to integrating any of Solaris's products.

note
  • The mandatory data points for this endpoint depend on various factors, such as the product, customer type (i,e., retail customers vs. freelancers), and branch.
  • 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 start to 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).

API reference

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

Related webhook events

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 you've collected from the customer in the request body of this endpoint:

Important

You have to submit the information exactly as they appear in official documents.

  • salutation
  • first_name (including all middle names as printed on the ID document)
  • last_name (including all name parts as printed on the ID document)
  • birth_date
  • birth_city
  • birth_country (ISO 3166-1 alpha-2 codes)
  • nationality (ISO 3166-1 alpha-2 codes)
  • address (Street, Number, City, Postal Code, Country, State).
  • contact_address (OPTIONAL To be used only if the customer's current address is younger than two years.)
  • mobile_number The mobile number here does NOT substitute creating and verifying the customer's mobile number using the relevant endpoints.
  • employment_status
  • data_terms_signed_at (UTC timestamp)
  • terms_conditions_signed_at (UTC timestamp)
  • own_economic_interest_signed_at (UTC timestamp)
  • fatca_relevant
  • fatca_crs_confirmed_at (UTC timestamp)
  • tax_information
    • tax_assessment (Indicates whether the customer files their taxes jointly or separately. Possible values are: NONE JOINT, or SEPARATE)
    • marital_status

Request example

Copy
Copied
POST /v1/persons
{
    "salutation": "MR",
    "first_name": "Peter",
    "last_name": "Mustermann",
    "nationality": "DE",
    "birth_date": "1972-12-14",
    "birth_city": "Berlin",
    "birth_country": "DE",
    "mobile_number": "+49301234567",
    "employment_status": "EMPLOYED",
    "address": {
        "line_1": "Musterstraße 10",
        "line_2": "",
        "postal_code": "10409",
        "city": "Berlin",
        "country": "DE",
        "state": "BE"
    },
    "tax_information": {
        "tax_assessment": "SEPARATE",
        "marital_status": "MARRIED"
    },
    "fatca_relevant": false,
    "fatca_crs_confirmed_at": "2017-01-01T00:00:00Z",
    "terms_conditions_signed_at": "2017-01-01T00:00:00Z",
    "own_economic_interest_signed_at": "2017-01-01T00:00:00Z"
}

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
01 Created
{
    "id": "6aeab6ab0146e0914edf335e6c1abce6cper",
    "salutation": "MR",
    "title": null,
    "first_name": "Peter",
    "last_name": "Mustermann",
    "address": {
        "line_1": "Musterstraße 10",
        "line_2": null,
        "postal_code": "10409",
        "city": "Berlin",
        "country": "DE",
        "state": "BE"
    },
   "email": null,
    "mobile_number": "+49301234567",
    "birth_name": null,
    "birth_date": "1972-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": "2017-01-01T00:00:00.000Z",
    "business_purpose": null,
    "industry": null,
    "industry_key": null,
    "terms_conditions_signed_at": "2017-01-01T00:00:00.000Z",
    "own_economic_interest_signed_at": "2017-01-01T00:00:00.000Z",
    "aml_follow_up_date": "2028-09-23",
    "aml_confirmed_on": "2022-03-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,
    "screening_progress": "NOT_SCREENED",
    "risk_classification_status": "NOT_SCORED",
    "customer_vetting_status": "NOT_VETTED",
    "annual_income_range": null,
    "data_terms_signed_at": null,
    "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

}

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:

attention

Fields not mentioned in this list can only be updated via Customer Support.

  • 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

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. Afterward, the customer enters the received OTP in your frontend to verify their number.

note

In Italy and Spain, this data point is required.

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.

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.

info

Check Appendix III for the TIN requirements per country.


Compliance disclaimer screen

Before beginning the identification process, your solution must display Solaris' compliance disclaimer and collect the customer's agreement. Please note the UI requirements below that explain how to display this text to your customers.

note

Partners may not change the compliance disclaimer text without the prior approval of Solaris' Compliance department. You may adapt the highlighted portions of the text to your own particular case.

I am hereby opening a bank account in my own name and I confirm the following:

  • I am fully legally responsible for all account activity.
  • I will use the account exclusively for private/business purposes.
  • I do not act on behalf of, or instructed by, a third person.

Beware of tricksters that try to mislead persons into opening bank accounts under false premises (e.g., app testing, job offers, credit brokering, identification for apartment offers) and misuse your account for criminal purposes.

Hiermit eröffne ich ein Konto in eigenem Namen und bestätige folgendes:

  • Ich allein trage die rechtliche Verantwortung für alle Kontobewegungen.
  • Ich nutze das Konto ausschließlich für private/geschäftliche Zwecke.
  • Ich handele nicht im Auftrag oder auf Veranlassung eines Dritten.

Vorsicht vor Trickbetrügern, die zur Kontoeröffnung unter falschem Vorwand verleiten (z.B. App-Testing, Job-Angebote, Kreditvermittlung, Identifikation für Wohnungssuche) und Ihr Konto für kriminelle Zwecke missbrauchen.

Compliance screen UI requirements

  • It must use the exact text provided above.
  • It must draw the customer's undivided attention—i.e., it cannot be hidden in the fine print.
  • It must be displayed as the only content on the screen, i.e., not combined with other information or something else.
  • It must be easily readable in a large font that fills the screen.
  • It must be displayed immediately before the customer is forwarded to the identification SDK flow.
  • The customer must confirm their understanding of and consent to the content of the screen, ideally for each paragraph individually.
  • The giving of consent must be performed by the user independently of any other interactions—i.e., it cannot coincide with the closing of the screen or the "next button".
  • You must store the customer's consent in a way that allows auditors to prove that the consent was given. Relying on the argument that the customer cannot proceed without consent is not sufficient.

Solaris recommends the following best practices:

  • When the compliance screen is displayed, there should be a short delay (e.g., one to three seconds) before the customer can click the consent button and continue (thereby incentivizing the customer to actually read the content).
  • Use a switch or checkbox design to give the customer the impression of a conscious consent, as opposed to just "clicking away" another screen.

Step 4: 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 (KYC)

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

Solaris offers different identification methods based on the product, region, and customer type. However, this guide explains the integration process of video identification with IDnow.

For an overview of available KYC methods, check the identity products overview page.

info
  • For customers who cannot identify with IDnow, check Fourthline KYC guide.
  • For more information about video identification, check the related guide for more contextual information.

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

API reference

Visit the following link to find all the endpoints related to the different methods of customer identification (KYC), including related properties and examples.

note

The previous link includes all endpoints for different KYC methods. This section includes the relevant endpoints required for video identification with IDnow.

Related webhook events


POST Check identification eligibility (Optional)

As an initial verification step, you can check whether the relevant customer is eligible for the given identification method or not based on their data, such as nationality, place of residence, or identification document.

This endpoint validates whether the person specified in the request URL is eligible to complete a given identification method. You must add the identification method for which you want to check the customer's eligibility in the request body.

Request example

Copy
Copied
POST /v1/persons/{person_id}/identification_eligibility_checks
{
  "method": "idnow"
}

Response example

The API call returns a response as to whether the person is eligible for identifying with a particular method or not. In case of failure, a reason is provided in the field failure_reason.

Copy
Copied
{
    "method": "idnow",
    "eligible": true,
    "failure_reason": "null"
}

Click here to view the full API reference

GET List supported documents for a person identification

Prior to redirecting your customer to complete the identification process, you can fetch the supported documents to share it with the customer beforehand.

This endpoint returns an array of document types that a customer may use to identify themselves along with a list of allowed issuing countries. The issuing_countries are provided as ISO country codes (ISO-3166-1 alpha 2). If the customer does not provide a supported document type in the identification process, then their identification will eventually fail.

Request URL

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

Click here to view the full API reference

POST Create identification

This endpoint creates an identification resource for the person specified in the request URL. You must add the following properties in the request body:

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

This endpoint does not send a request to the identification provider to start the identification process.

Request example

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

Response example

The API call returns an identification object with a unique id, the identification_id, as well as the identification status, set initially to created.

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

Click here to view the full API reference.

PATCH Request person identification

This endpoint triggers the identification flow with IDnow for the specific customer. The status of the identification will change to pending after calling this endpoint.

Request URL

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

Response example

The API call returns the identification object with the status pending. The status remains pending until the customer completes the identification. Additionally, the payload includes the url (valid for 14 days), which the customer can use to identify via the web browser, and the reference, which is the identification token (format: ABCDEFGH ), an internal IDnow identifier the customer can use to video-identify through IDnow's mobile application (available on iOS and Android).

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

Click here to view the full API reference.

Redirect the customer to IDnow to complete the identification process. You can also share with the customer the supported documents that they must present during the session.

IDnow Video-identification process

  • Before being put in touch with a video identification agent, your customer is redirected to an IDnow-branded landing page, where they are asked to give their consent to IDnow's Terms & Conditions and confirm that they have a valid ID document at hand. This ID document will be shown via webcam to the agent during the video identification.

  • Additionally, your customer must also provide their valid mobile number during their identification. IDnow agent will verify this mobile number by sending an SMS OTP, which the customer will need to provide during the call. Solarisbank will re-use the verified mobile number of a successful IDnow video identification as the customer's verified mobile number.

  • Once connected with an IDnow agent, your customer is greeted on behalf of Solarisbank ( « You are identifying for a service of Solarisbank » ) or on your behalf ( « You are identifying for a service of /Your Brand Name/, empowered by Solarisbank » ), depending on the setup you have agreed upon with Solarisbank.

  • The call takes place either in English or in German. The agent goes on to verify the customer's mobile number and the customer's data, such as first_name and last_name. In addition, the agent populates specific additional attributes of the person resource during the call.

note

While most video identifications are immediately set to successful, an identification status could be set to an intermediary status pending_successful. In such cases, a second-line agent at IDnow reviews the outcome of the video identification. This process typically takes minutes but can take up to 24 hours before the identification status is updated to a final successful status. However, you can already offer services to the customer until the review results.

GET Retrieve person identification

This endpoint returns a completed person identification (i.e., the person identification process was successful). If you use the include_documents filter, this method will also return the documents submitted by the customer during the identification process.

To download any of the documents submitted during the identification process, you can use the document unique id and download the files using the Document resource endpoints.

Request URL

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

Response example

Copy
Copied
{
  "id": "6dc54352d6793a892e0702850d07b831cidt",
  "reference": "TST-KCCEY",
  "url": "https://go.test.idnow.de/solarisbankvideoidentsandbox/identifications/6dc54352d6793a892e0702850d07b831cidt",
  "status": "successful",
  "completed_at": "2022-07-14T18:18:28.000Z",
  "method": "idnow",
  "proof_of_address_type": "GAS_BILL",
  "proof_of_address_issued_at": "2022-03-03",
  "language": "DE",
  "person_id": "7cf09c3c5547b974a664201f24b454eecper",
  "address": {
    "line_1": "Amrumerstrasse",
    "line_2": "14",
    "postal_code": "13353",
    "city": "Berlin",
    "country": "DE"
  },
  "documents": [
    {
      "id": "448b75fa1c57eecda41d91c66c22faa6cdoc",
      "name": "file1.pdf",
      "content_type": "application/json",
      "document_type": "KYC_REPORT",
      "size": 803580
    },
    {
      "id": "94eb22a9311be9a1fbb698c448b0b337cdoc",
      "name": "file2.jpg",
      "content_type": "image/jpeg",
      "document_type": "SIGNATURE",
      "size": 25349
    }
  ]
}

Click here to view the full API reference.

Other identification endpoints


Customer due diligence (CDD)

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.


Screen for FATCA indicia

You must now determine whether the customer is subject to US tax law. Solaris is required to perform this check in order to comply with the Foreign Account Tax Compliance Act (FATCA). These checks must be performed in addition to the self-identification during the Legal and Compliance screen.

For this, you must parse the person and identification resources. To do so, you can use the following endpoints:

Hard criteria

You must screen the customer for the following hard criteria to determine FATCA relevance:

  • Has the customer provided a US passport as their identification document? (legitimation_country attribute on the identification)
  • Is the customer a citizen of the US? (nationality attribute)
  • Has the customer provided a residential address in the US, the US Minor Outlying Islands, or the US Virgin Islands? (country attribute)
  • Was the customer born in the US, the US Minor Outlying Islands, or the US Virgin Islands? (birth_country attribute)

When to reject the customer

If any of the hard criteria attributes has the value of US or USA, then the customer cannot be onboarded. The process must stop here.

Failure to screen for hard FATCA criteria may cause ongoing operational burdens for partner customer support.

Soft criteria

Next, screen the customer for the following soft criteria to determine FATCA relevance:

  • Has the customer provided a US mobile number (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? (address_line_1 and address_line_2 attributes)

When to reject the customer

  • If the answer is "Yes" to any of the soft criteria, then you must ask the customer to clarify their phone number and/or address.
    • Then, if the customer provides a non-US phone number and a physical address, they can be onboarded.
  • If the customer does not provide a non-US phone number and a physical address, they cannot be onboarded.

Failure to screen for soft FATCA criteria may cause ongoing operational burdens for partner customer support.

attention

Please note Solaris runs periodic checks on the FATCA relevance for existing customers. If the FATCA relevance changes to true for an existing customer, Solaris's Customer Support team will contact you with instructions for the next steps.


Step 5: Set up customer account

Congratulations

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

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

Order / Open account

Bestellen / Konto eröffnen

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

API reference

Visit the following links to find all the endpoints related to person accounts, including related properties and examples.

POST Create an account

After the customer clicks the button to open an account, call this API endpoint and include the customer's person_id in the request URL. Additionally, specify the account type by adding the following property in the request body:

  • type: Set the value to CHECKING_PERSONAL.

Request URL:

Copy
Copied
POST /v1/persons/{person_id}/accounts
{
    "type": "CHECKING_PERSONAL",
    "purpose": "primary" 
}

Response example

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

Copy
Copied
{
  "id": "efe320cbe121418c982b6af45bc9cacc",
  "iban": "DE43110101005555555555",
  "bic": "SOBKDEB2XXX",
  "type": "CHECKING_PERSONAL",
  "purpose": "primary",
  "currency": "EUR",
  "balance": {
    "value": 0,
    "unit": "cents",
    "currency": "EUR"
  },
  "available_balance": {
    "value": 0,
    "unit": "cents",
    "currency": "EUR"
  },
  "locking_status": "NO_BLOCK",
  "locking_reasons": "null",
  "account_limit": {
    "value": 0,
    "unit": "cents",
    "currency": "EUR"
  },
  "person_id": "0ba2211cab11af6094d60ead81f2bd9dcper",
  "business_id": "null"
}

Click here to view the full API reference.


Step 6: Create and activate card

Now that you have fully onboarded your customer, you can create a card for them. See the Cards guides for an overview about cards.

API reference

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

POST Create a card

This endpoint initiates the card creation process for the customer. Include the account_id returned by the POST Create an account API call (in the previous step) along with the person_id in the request URL. Additionally, include the following properties in the request body:

  • line_1: The cardholder's name which will be printed on the card. Pay attention to the special rules governing card names mentioned here.
  • type: The card type. View here a list of possible card types for each customer segment.

Request URL:

Copy
Copied
POST /v1/persons/{person_id}/accounts/{account_id}/cards

Response example:

A card will be created in the system, and Solaris will issue a card creation request with SIA. The API will respond with the ID of the card and the status of PROCESSING.

Copy
Copied
{
  "id": "8febdba4912a747808ccc6f95f82aaa4",
  "status": "PROCESSING"
}

Click here to view the full API reference.

GET Retrieve card details

Before you can activate the card, make the following API call to retrieve the details of the card. The status must have the value of INACTIVE. The status change may take a few seconds after the initial POST Create card request, as Solaris submits card creation requests asynchronously to SIA.

Request URL:

Copy
Copied
GET /v1/cards/{card_id}

Response example:

The API will respond with the card details when the status changes to INACTIVE. Until then, the response will look the same as the one from the previous call.

Copy
Copied
{
  "id": "8febdba4912a747808ccc6f95f82bbb4",
  "type": "VISA_DEBIT",
  "status": "INACTIVE",
  "expiration_date": "2022-09-07",
  "person_id": "2444a25c7485027c4737fca70f10c958",
  "account_id": "33c91e76c888d578e6ce1b22086cc7e7",
  "business_id": null,
  "representation":{ 
    "line_1": "FIRSTNAME LASTNAME", 
    "masked_pan": "434970******4567", 
    "formatted_expiration_date": "09/22" 
  },
  "creation_date": "2020-02-31T10:23:16.000Z",
  "sia_account_number": "500001650679"
}

Click here to view the full API reference.

POST Activate a card

Once the card is INACTIVE and you have retrieved the details using the previous API call, you can activate the card using the following endpoint:

Request URL:

Copy
Copied
POST /v1/cards/{card_id}/activate

Response example:

The status of the card will change to ACTIVE, and the customer will be able to use it right away.

Copy
Copied
{
  "id": "8febdba4912a747808ccc6f95f82bbb4",
  "type": "MASTERCARD_DEBIT",
  "status": "ACTIVE",
  "expiration_date": "2022-09-07",
  "person_id": "2444a25c7485027c4737fca70f10c958",
  "account_id": "33c91e76c888d578e6ce1b22086cc7e7",
  "business_id": null,
  "representation": {
    "line_1": "FIRSTNAME LASTNAME",
    "masked_pan": "537458******4567",
    "formatted_expiration_date": "09/22"
  }
}

Click here to view the full API reference.

Card push provisioning

If your customer wants to use their card in a digital wallet, such as Google Pay, Apple Pay, or Samsung Pay wallet, implement the relevant endpoints in the Card Push Provisioning guide.


What's next?

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

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

Mandatory features

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

Compliance requirements

Authentication & authorization

Digital Banking & Cards


Appendix I: Enums

Document types

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

EnumDescription
ANNUAL_FINANCIAL_STATEMENTA business or a company's annual financial statement.
KYC_REPORTThe KYC report generate after a successful customer identification.
ID_DOCUMENTAn person's identification document, such as passport or ID.
SIGNATUREA signature example.
PICTUREA picture or a scanned document of any other type.
QES_DOCUMENTA document related to a Qualified Electronic Signature (QES).
SIGNED_CONTRACTA signed contract of any kind.
SIGNED_QES_DOCUMENTA document signed by a Qualified Electronic Signature (QES).
REGISTER_CHECKA register check.
REGISTER_EXTRACTA business or a company's commercial register excerpt or a similar document.
FOUNDATION_DOCUMENTThe foundation document of a company or business.
SCHUFA_COMPACT_REPORTA compact SCHUFA report.
SCHUFA_GWG_REPORTA GWG SCHUFA report.
SCHUFA_FULL_REPORTA full SCHUFA report about a person.
SCHUFA_SHORT_REPORTA short SCHUFA report about a person.
CREDIT_AGENCY_REPORTA report issued by a credit agency.
SHARE_HOLDERS_AGREEMENTA business or a company's shareholders agreement.
SHAREHOLDERS_LISTA business or a company's shareholders list.
TRADING_LICENSEA business or a company's trading license.
TRANSPARENCY_REGISTER_EXTRACTAn extract of a transparency register.
INVOICEAn invoice of any kind.
OTHERAny other type of document.
VIDEOA video of any kind.
VAT_CERTIFICATEVAT 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.

StatusDescription
createdThe identification resource has been created for the customer.
pendingThe 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_successfulThe 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_failedThe 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.
successfulThe video identification was successful. The customer can be onboarded. Please note that the customer's data might have been updated during the identification session.
abortedThe customer aborted the identification process. The customer can still video-identify using the same URL.
canceledThe provider canceled the video identification. The customer should video-identify again using the same URL.
failedThe 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.

DocumentIssuer CountryType (ID/PP)
MLT-BO-02001MaltaID
MLT-BO-03001MaltaID
SVK-BO-02001SlovakiaID
SVK-BO-05001SlovakiaID
SVK-BO-04001SlovakiaID
ITA-BO-04003ItalyID
ITA-BO-03004ItalyID
ITA-BO-03002ItalyID
ITA-BO-03001ItalyID
ITA-BO-03003ItalyID
DEU-BO-01003GermanyID
DEU-BO-02001GermanyID
SGP-BO-01001-ASingaporeID
SGP-BO-01001SingaporeID
CZE-BO-04001Czech RepublicID
CZE-BO-04002Czech RepublicID
IND-AO-01001IndiaPassport
CHN-AO-04003ChinaPassport
BGR-AO-01005BulgariaPassport
SVN-AO-02001-02003SloveniaPassport
SVN-AO-02004SloveniaPassport
SVN-BO-02001SloveniaID
SVN-AO-01004SloveniaPassport
POL-BO-02001-02003PolandID
ESP-BO-03001SpainID
ESP-BO-05001SpainID
HRV-BO-02001CroatiaID
HRV-AO-02001CroatiaPassport
FRA-BO-02002FranceID
FRA-AO-03001-03003FrancePassport
MAR-AO-02001MoroccoPassport

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)
1Ain01
2Aisne02
3Allier03
4Alpes-de-Haute-Provence04
5Hautes-Alpes05
6Alpes-Maritimes06
7Ardèche07
8Ardennes08
9Ariège09
10Aube10
11Aude11
12Aveyron12
13Bouches-du-Rhône13
14Calvados14
15Cantal15
16Charente16
17Charente-Maritime17
18Cher18
19Corrèze19
21Côte-d'Or21
22Côtes-d'Armor22
23Creuse23
24Dordogne24
25Doubs25
26Drôme26
27Eure27
28Eure-et-Loir28
29Finistère29
2ACorse-du-Sud2A
2BHaute-Corse2B
30Gard30
31Haute-Garonne31
32Gers32
33Gironde33
34Hérault34
35Ille-et-Vilaine35
36Indre36
37Indre-et-Loire37
38Isère38
39Jura39
40Landes40
41Loir-et-Cher41
42Loire42
43Haute-Loire43
44Loire-Atlantique44
45Loiret45
46Lot46
47Lot-et-Garonne47
48Lozère48
49Maine-et-Loire49
50Manche50
51Marne51
52Haute-Marne52
53Mayenne53
54Meurthe-et-Moselle54
55Meuse55
56Morbihan56
57Moselle57
58Nièvre58
59Nord59
60Oise60
61Orne61
62Pas-de-Calais62
63Puy-de-Dôme63
64Pyrénées-Atlantiques64
65Hautes-Pyrénées65
66Pyrénées-Orientales66
67Bas-Rhin67
68Haut-Rhin68
69Rhône69
70Haute-Saône70
71Saône-et-Loire71
72Sarthe72
73Savoie73
74Haute-Savoie74
75Paris75
76Seine-Maritime76
77Seine-et-Marne77
78Yvelines78
79Deux-Sèvres79
80Somme80
81Tarn81
82Tarn-et-Garonne82
83Var83
84Vaucluse84
85Vendée85
86Vienne86
87Haute-Vienne87
88Vosges88
89Yonne89
90Territoire de Belfort90
91Essonne91
92Hauts-de-Seine92
93Seine-Saint-Denis93
94Val-de-Marne94
95Val-d'Oise95
971Guadeloupe97
972Martinique97
973Guyane97
974La Réunion97
976Mayotte97
99Other (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

Position12345678910111213141516
DigitRSSMRA99D20F205R
Position in fiscal codeMeaning of digitsHow it is computed
1-3Last nameLast 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-6First nameLast 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-8Year of birthLast two digits of the birth year (e.g., for customers born in 1975, these digits would be 75).
9Month of birthThe 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-11Day of birth & genderThese 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-15Place of birthThese 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.
16Control characterThe 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.
DuplicatesIn 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

CharacterValueCharacterValueCharacterValueCharacterValue
0099I8R17
11A0J9S18
22B1K10T19
33C2L11U20
44D3M12V21
55E4N13W22
66F5O14X23
77G6P15Y24
88H7Q16Z25

Table 2

CharacterValueCharacterValueCharacterValueCharacterValue
01921I19R8
10A1J21S12
25B0K2T14
37C5L4U16
49D7M18V10
513E9N20W22
615F13O11X25
717G15P3Y24
819H17Q6Z23

Table 3

CharacterValueCharacterValueCharacterValueCharacterValue
0A7H14O21V
1B8I15P22W
2C9J16Q23X
3D10K17R24Y
4E11L18S25Z
5F12M19T
6G13N20U

Table 4

MonthValueMonthValueMonthValueMonthValue
JanuaryAAprilDJulyLOctoberR
FebruaryBMayEAugustMNovemberS
MarchCJuneHSeptemberPDecemberT

Table 5

CharacterValueCharacterValueCharacterValueCharacterValue
0L3P6S9V
1M4Q7T
2N5R8U

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