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.

User journey

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

1. The customer applies for a decoupled card with Solaris and agrees to the terms and conditions, credit checks, and account snapshot.
2. After passing the credit checks stage, the customer is offered a decoupled card with a specific credit limit (i.e., an overdraft limit).
3. The customer goes through the customer identification process (KYC).

4. After a successful identification, you will create an internal bank account (with type DECOUPLED_CARD_PERSONAL) for the customer. The offered credit limit is attached to this account and linked to the associated debit card.

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

Decoupled card usage

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

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

SDD orchestration

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

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

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

Accounts

A decoupled card involves different bank accounts:

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

   • Note: Customers can have multiple reference accounts tied to their decoupled card. Consult your Partner Manager for more information about setting up multiple reference accounts.
2. Internal account: An internal Solaris account created for a decoupled card. The overdraft (i.e., the credit limit available on the card) is attached to this account. Solaris credits the funds from the customer's reference account to this account via SDD to settle any negative balance.

3. (Optional) Round-up account: The customer can opt for a round-up account associated with the decoupled card. The customer specifies a round-up amount for each purchase (e.g., rounding up the purchase amount to the nearest value). In this case, the SDD includes the purchase amount (transferred to the internal account) and the round-up amount (transferred to the round-up account).

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

Credit scoring

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

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

Which information does the credit scorer use?

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

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

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

System prerequisites

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

1. Technical setup:

Set up your environment and get your authentication keys. For step-by-step instructions, check the Technical setup guide.

2. Legal and compliance screens:

Build the necessary legal and compliance screens in your sign-up flow to collect your customers' consent to the necessary legal and compliance requirements. The Legal and compliance screens guide contains step-by-step instructions on how to create these screens and what they must contain.

Record the customer's consent on each screen as a UTC timestamp (e.g., 2019-01-01T00:00:00Z). Afterward, you must pass each timestamp in its respective field to Solaris.

• Collect the customer's consent to Solaris's Terms and Conditions and store the timestamp in the terms_conditions_signed_at field.
• Collect the customer's consent to data processing and store the timestamp in the data_terms_signed_at field.
• Collect the customer's economic interest declaration and store the timestamp in the own_economic_interest_signed_at field.
• Collect the customer's FATCA indication and store it in the fatca_relevant field. Store the timestamp in the fatca_crs_confirmed_at field.

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

• ACCOUNT_LIMIT_CHANGE
• ACCOUNT_SNAPSHOT
• SDD_COLLECTION_APPLICATION
• PERSON_CREDIT_RECORD

Integration flow

Integration steps

User registration

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

SDD collection application

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

Customer identification and due diligence

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

Accounts and card setup

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

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

Step 1: Collect customer data and create person resource

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

What is a person resource?

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

API reference

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

• Person resource API reference:

  • POST Create person
  • GET Retrieve a person
  • PATCH Update person

Related webhook events

• PERSON_CHANGED
• PERSON_DELETED

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

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:

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

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

API reference

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

• Mobile number resource API reference

Related webhook events

• PERSON_MOBILE_NUMBER_CREATED
• PERSON_MOBILE_NUMBER_DELETED

POST Create mobile number

Collect the customer's mobile number and pass it to Solaris using the following API call, and include the customer's person_id in the request URL.

Request example:

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

Response example:

The API returns a mobile_number resource with a unique id and attaches it to the person resource.

{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": false
}

Click here to view the full API reference.

POST Authorize mobile number

Use the following endpoint to verify the ownership of the provided mobile phone number. The endpoint initiates a one-time-password (OTP) flow: Solaris sends a six-digit OTP to the customer's number, and then they must enter it in your UI.

Request example:

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

Response example:

{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": false
}

Click here to view the full API reference..

POST Confirm mobile number

Use this endpoint to submit the SMS OTP the customer received on their mobile number to finalize the mobile number authorization process. You must add the customer's number and token (i.e., the SMS OTP) in the request body. Afterward, the mobile number will be verified and can be used in the context of Strong Customer Authentication (SCA).

Request example:

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

Response example:

{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": true
}

Click here to view the full API reference.

Mobile number management

For more information about how to manage mobile numbers, check the related guide.

Step 3: Create customer tax identification

In this step, 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.

• Person tax identifications API reference:

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

Related webhook events

• PERSON_TAX_IDENTIFICATION_CHANGED

POST Create person tax identification

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.

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.

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"
            }
        }
    ]
}

Tax ID testing data

You can use the following test values for the TIN to test these endpoints on Sandbox:

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.

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.

• Credit record resource API reference

POST Create a credit record for a retail customer

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

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

Request URL

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

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.

• Account snapshot resource API reference

POST Create an account snapshot for a customer

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

1. Account snapshot via FinTech systems

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

1. Integrate the FIN_TECH_SYSTEMS wizard container in your solution by following their documentation.

2. Call the following endpoint and add the following properties in the request body:

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

Request example

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:

1. Integrate the FinX widget in your solution by following their documentation.

2. Call the following endpoint and add the following properties in the request body:

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

Request example

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}

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

Customer due diligence

Check the related guide for more information.

Step 8: Set up customer internal account

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.

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.

• Reference accounts resource API reference:

  • POST Create a reference account for a person
  • GET Index reference accounts for a person

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.

Change the SDD collection limit

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

POST Create an SDD collection limit on the customer account

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

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

Request URL

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 is CUSTOMER_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:

POST Initiate a payout to a specific reference account

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

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

Request URL

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

• Device binding
• Strong Customer Authentication (SCA)
• 3DS
• PSD2 SCA flow

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.

Document types

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

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.

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.

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

  • Note: Relevant 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

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

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.

  • line_1
  • line_2
  • postal_code
  • city
  • country: Only IT 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 Only IT 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 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

• salutation

  • Note: MR for male (Sr. or Señor), MS for female (Sra. or Señora); no gender-neutral options allowed.

• 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: Only ES 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 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
• 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

Table 1

Table 2

Table 3

Table 4

Table 5

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