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:
- The customer applies for a decoupled card with Solaris and agrees to the terms and conditions, credit checks, and account snapshot.
- After passing the credit checks stage, the customer is offered a decoupled card with a specific credit limit (i.e., an overdraft limit).
- The customer goes through the customer identification process (KYC).
-
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.
- 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.
- 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:
-
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.
- 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.
-
(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 thefatca_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.
- ACCOUNT_BLOCK
- ACCOUNT_CLOSURE
- ACCOUNT_CLOSURE_REQUEST
- BOOKING
- CARD_LIFECYCLE_EVENT
- CARD_AUTHORIZATION
- CARD_AUTHORIZATION_DECLINE_V2
- CARD_AUTHORIZATION_RESOLUTION
- CARD_FRAUD_CASE_PENDING
- CARD_FRAUD_CASE_TIMEOUT
- IDENTIFICATION
- PERSON_CHANGED
- PERSON_DELETED
- PERSON_SEIZURE_CREATED
- PERSON_SEIZURE_DELETED
- PERSON_SEIZURE_FULFILLED
- PERSON_SEIZURE_UPDATED
- PERSON_MOBILE_NUMBER_CREATED
- PERSON_MOBILE_NUMBER_DELETED
- PERSON_TAX_IDENTIFICATION_CHANGED
- POSTBOX_ITEM_CREATED
- POTENTIAL_ACCOUNT_BLOCKING
- SCA_CHALLENGE
Integration flow
Integration steps
User registration
- 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.
- Create and verify the customer's mobile number by completing Step 2.
- Implement the device binding process for the customer.
- Create a person tax identification by completing Step 3.
SDD collection application
- Create a credit record for the customer by completing Step 4.
- Create SDD collection application by completing Step 5.
- Create an account snapshot and attach it to the SDD application by completing Step 6.
Customer identification and due diligence
- Create an identification resource for the customer and specify the identification method by completing Step 7.
- Redirect the customer to complete the chosen identification process.
- 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
- Create an internal account for the customer and link it to the SDD collection application by completing Step 8.
- Create the reference account and SDD mandate by completing Step 9.
- 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
andlast_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 forfirst_name
,last_name
,birth_city
, andbirth_date
). If you create more than 1000 identicalperson
resources, then the API will return a400
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:
{
"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).
Address validation
Your solution must implement address validation to ensure that your system rejects non-existent or wrong address entries before the customer goes through the identification flow. In addition, please note the following best practices:
- Select a reliable provider to ensure the accuracy and actuality of data.
- Address validation must happen in real-time when the customer enters their address during the onboarding flow.
- The system can make auto-complete suggestions to the customer when entering the address. Additionally, it must reject non-existent or wrong entries.
- If the address validation fails, the customer can enter a nearby address and proceed with the identification flow. However, the customer must submit a proof of address afterward to customer support, such as a rental contract, electricity bill, or certificate of residence in Germany (i.e., Meldebescheinigung).
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
line_1
line_2
postal_code
city
country
(ISO 3166-1 alpha-2 codes)
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
-
marital_status
(Possible values below):SINGLE
MARRIED
WIDOWED
DIVORCED
UNKNOWN
-
iban
: Only required for Bankident.
Request example
// 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": {
"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",
"own_economic_interest_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.
{
"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": null,
"marital_status": "MARRIED"
},
"fatca_relevant": false,
"fatca_crs_confirmed_at": "2022-01-01T00:00:00.000Z",
"business_purpose": null,
"industry": null,
"industry_key": null,
"terms_conditions_signed_at": "2022-01-01T00:00:00.000Z",
"own_economic_interest_signed_at": "2022-01-01T00:00:00Z",
"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
toFREELANCER
orSELF_EMPLOYED
, please note that you must do one of the following options in the same request to avoid getting an error:- Collect the
nace_code
from the customer, or - Set the fields
industry
andindustry_key
tonull
.
- Collect the
- It's recommended to collect the
nace_code
from the customer for data quality.
Request URL
PATCH /v1/persons/{id}
Click here to view the full API reference
Step 2: Create and verify mobile number
In this step, 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:
POST /v1/persons/{person_id}/mobile_number
{
"number": "+15550101"
}
Response example:
The API returns a mobile_number
resource with a unique id
and attaches it to the person
resource.
{
"id": "91e4d939d781b8eb30d1ee86809761c2cmno",
"number": "+15550101",
"verified": false
}
Click here to view the full API reference.
POST Authorize mobile number
Use the following endpoint to verify the ownership of the provided mobile phone number. The endpoint initiates a one-time-password (OTP) flow: Solaris sends a six-digit OTP to the customer's number, and then they must enter it in your UI.
Request example:
POST /v1/persons/{person_id}/mobile_number/authorize
{
"number": "+15550101"
}
Response example:
{
"id": "91e4d939d781b8eb30d1ee86809761c2cmno",
"number": "+15550101",
"verified": false
}
Click here to view the full API reference..
POST Confirm mobile number
Use this endpoint to submit the SMS OTP the customer received on their mobile number to finalize the mobile number authorization process. You must add the customer's number
and token
(i.e., the SMS OTP) in the request body. Afterward, the mobile number will be verified
and can be used in the context of Strong Customer Authentication (SCA).
Request example:
POST /v1/persons/{person_id}/mobile_number/confirm
{
"number": "+15550101",
"token": "212212"
}
Response example:
{
"id": "91e4d939d781b8eb30d1ee86809761c2cmno",
"number": "+15550101",
"verified": true
}
Click here to view the full API reference.
Mobile number management
For more information about how to manage mobile numbers, check the related guide.
Step 3: Create customer tax identification
In this step, 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:
-
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
- 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 givencountry
, the API will return a400
error. - Check the appendix Tax Identification Number (TIN) by country for details on how to validate the customer's TIN.
- The API automatically validates the
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 aPerson
must be the primary tax identification. If anothertax_identification
with the value ofprimary
set totrue
is created, it will set theprimary
value of the previously createdtax_identification
tofalse
. - Each
Person
may only have onetax_identification
percountry
.
- The first
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 areNOT_ASSIGNED_YET
,NOT_ASSIGNED_BY_COUNTRY
,OTHER
.reason_description
: Free text description of why no TIN was provided. Applies only if thereason_no_tin
isOTHER
.
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:
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
.
{
"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
{
"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 arepartner
orsolarisBank
.file
: The file of the credit record Base64-encoded. Only required Ifsource
is set topartner
.
Request URL
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
.
{
"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
GET /v1/persons/{person_id}/credit_records/{credit_record_id}
Response example
{
"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
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
.
{
"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
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:
- Integrate the FIN_TECH_SYSTEMS wizard container in your solution by following their documentation.
-
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.
- 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. - The customer enters their bank credentials to initiate the account snapshot.
Request example
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
.
{
"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:
- Integrate the FinX widget in your solution by following their documentation.
-
Call the following endpoint and add the following properties in the request body:
- source: FINREACH
- 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
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.
{
"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
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
.
{
"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
{
"source": "SOLARISBANK",
"account_id": "adc123a45d6d7cf8fbfeed537ba919d5cacc"
}
Response example
The API call returns a resource with a unique ID, the account_snapshot_id
.
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
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
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:
- Bankident (Only for customers with a German IBAN).
- Video identification (Only for customers with supported identification documents).
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
- Your customer must be successfully identified and screened before creating an account. You must complete Step 7: Complete the customer identification and due diligence process before completing this step.
- The
status
of the SDD collection application must reach theoffered
stage.
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
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.
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
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 a reference account for the customer.
Create B2C SDD mandate
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: Solaris SE
- Legal text containing an authorization for the mandate
Reference accounts API reference
Visit the following link to find all the endpoints related to the reference account resource, including related properties and examples.
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
// 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
.
{
"id": "1231231239ref",
"status": "ACTIVE",
"name": "Max Mustermann",
"iban": "DE32110101001000000029",
"mandate_number": "SAMPAY7D226d32882d11Eb8DcD0242Ae2F4",
"mandate_signature_date": "2022-04-20"
}
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. UseCUSTOMER_REQUEST
.
Request URL
POST /persons/{person_id}/accounts/{account_id}/sdd_collection_limits
Response example
{
"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 isCUSTOMER_REQUEST
.
Request URL
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, includingvalue
,unit
, andcurrency
.description
: Field to add additional description for the transaction.
Request URL
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.
{
"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
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
- Terms & Conditions Consent Log
- Seizures
- GDPR deletion requests
- Account closure
- Postbox
- AML update process
Authentication & authorization
Digital Banking & Cards
- Account management
- Cards creation and servicing
- Cards Smart Agent
- Encrypted PIN change
- Foreign exchange markup
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
- List of the accepted passports for videoIdent: here
- List of accepted passports for postIdent: here
- 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.
- Note:
first_name
last_name
-
branch
- Note: Must be
FR
.
- Note: Must be
-
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
.
- Note: Same type as
- (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
orSELF_EMPLOYED
, then thenace_code
,socioprofessional_category
andwork_country
parameters should be made available.
-
nace_code
- Note: Relevant NACE code
-
work_country
- Note: Same type as
country
.
- Note: Same type as
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
-
marital_status
(Possible values below:)SINGLE
MARRIED
DIVORCED
WIDOWED
UNKNOWN
-
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.
- Note:
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
.
- Note: Same type as
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.
- Note:
first_name
last_name
-
branch
- Note: Must be
IT
.
- Note: Must be
-
address
(Italian: residenza): The customer's legal residence. Must contain the street name and house number.line_1
line_2
postal_code
city
country
: OnlyIT
is allowed.state
: 2-digit Italian province code. Click here for a full list of province codes.
-
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.line_1
line_2
postal_code
city
country
OnlyIT
is allowed.state
: 2-digit Italian province code. Click here for a full list of province codes.
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 NOTIT
, then the value must be set toEE
.
- Note: If the customer's
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
orSELF_EMPLOYED
, then thenace_code
andwork_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
ofEMPLOYED
orSELF_EMPLOYED
.
- Note: Only applies to customers with an
work_country
: 2-digit ISO 3166-2 code.work_province
: (Only provide if thework_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
-
salutation
- Note:
MR
for male (Sr. or Señor),MS
for female (Sra. or Señora); no gender-neutral options allowed.
- Note:
-
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
line_1
(Street name, Number)line_2
(Floor, Door)postal_code
city
country
: OnlyES
is allowed.state
: 2-digit Spanish province code. Click here for a full list of Spanish province codes.
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
nace_code
work_country
: 2-digit ISO 3166-2 code.work_province
(Only provide ifwork_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
self_declared_as_pep
(boolean)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).