Consumer loans

This guide explains the integration process of Solaris' Loan product for retail customers (Consumers) as a standalone solution, including the mandatory information you must collect from your customers and the necessary endpoints and webhooks you must integrate into your solution.

Introduction

Product specifications

Solaris' Consumer Loans product enables you to offer loans to your retail customers in a simple and efficient workflow. With just a few API calls and an automated credit scoring system, you can create loan applications, identify your customers, issue loan payouts, and maintain consumer loans.

Solaris' consumer loans are versatile and can be tailor-made to your use case. Our standard offering includes loan amounts ranging from EUR 1,000 to 50,000 and loan terms from 12-84 months. You can choose between a standard loan or a loan tied to financing the purchase of goods.

Important

Consumer loans are currently only offered to customers in Germany with at least one German bank account.

User journey

Your customers can apply for a loan by completing the following steps:

  • Enter their desired amount and loan term on your frontend to receive an anonymous non-binding loan offer.
  • Apply for a loan officially and provide the mandatory information.
  • Consent to Solaris' terms and conditions and the credit scoring process, which will be done in relation to their credit line application.
  • If their application is approved, they'll receive the binding loan offer (SECCI form) and contract, which they must review before the identification process.
  • Complete the identification process and sign the loan contract.
  • The loan amount will be credited to their account and they can use it right away!

Credit scoring

Solaris uses an automated retail credit scoring system to make informed credit decisions on consumer loan 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 different credit checks done throughout the application lifecycle, the scorer estimates the probability of default (PD) and then determines whether to offer a loan. It also determines the amount, term, and interest rate to be offered.

How does the scorer interact with the consumer loan service?

The consumer loan service and its related endpoints handle consumer loan requests and collect the required information about the applicants, such as self-declared financial information, credit records, and account snapshots. Throughout the lifecycle of a consumer loan application, the scorer provides different responses based on the information provided during each stage of the application.

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

  • Anonymous offer: In this stage, the scorer evaluates the self-declared information the applicant provided when requesting an anonymous non-binding loan offer. The scorer gives an immediate decision to the customer. This check only happens if you've implemented the anonymous offer endpoint in your solution.
  • Binding offer: The scorer decides whether to make a binding offer by analyzing the consumer loan application and the credit record obtained from external credit bureaus, such as SCHUFA.
  • Verification: The scorer uses the account snapshot to verify the financial information provided in the consumer loan application. This is the final check, after which the scorer provides the final decision.

System prerequisites

Before integrating Solaris' Consumer Loans, 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.

Create the following screens and record your customers' 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.

For step-by-step instructions, check the Legal and compliance screens guide.

note

The mentioned fields are part of the person resource, in which you will store all customer data points.


Webhooks

Solaris recommends subscribing to the following webhook events to better automate your processes:

  • IDENTIFICATION: The status of a person identification has changed.
  • PERSON_CHANGED: One or more attributes of the person object changed. Contains only person_id and no payload.
  • PERSON_DELETED: Solaris deletes all personal data related to the given person from its system according to GDPR regulations. You are legally required to delete all personal information related to the customer specified in the payload as soon as you receive this webhook notification.
  • PERSON_MOBILE_NUMBER_CREATED: A mobile number was created for a customer, but has not yet been verified.
  • ACCOUNT_SNAPSHOT: The status of a customer's account snapshot has changed.
  • PERSON_CREDIT_RECORD: The status of a customer's credit record has changed.
  • CONSUMER_LOAN_APPLICATION: The status of the consumer loan application has changed.
  • LOAN: The status of a loan has changed.

For detailed instructions on implementing Solaris webhooks, check the webhooks documentation.


Integration flow

Integration steps

Important
  • This guide includes the integration process for Consumer Loans as a standalone solution, i.e., the loan will be credited to an external account.
  • For existing customers who already have a current account with Solaris and wish to apply for a loan, skip Step 1.

Integrate Solaris' Consumer Loans by completing the following steps:

User registration

  1. (Optional) Generate an anonymous loan offer for the customer by completing Step 0.
  2. 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.

Consumer loan application

  1. Create a credit record for the customer by completing Step 2.
  2. Create a consumer loan application by completing Step 3.
  3. Create an account snapshot by completing Step 4.
  4. Complete the steps related to contracting signing, such as sending the SECCI form and the final contract in Step 5.

Customer identification and e-signing

  1. Complete the customer identification and e-signing process by completing Step 6
  2. Redirect the customer to complete the identification process.
  3. Ensure that the customer is successfully identified and passes the risk screening before proceeding with the following steps.

Loan creation and servicing

  1. Create the loan for the customer to trigger the payout by completing Step 7.
  2. Complete Step 8 to implement the endpoints related to loan servicing and maintenance in your solution.

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


Step 0: Generate an anonymous offer for a loan (Optional)

In this step, you can give your customers the opportunity to receive a non-binding anonymous loan offer before starting the loan application process or providing any personal data. This is an optional step that you can implement in your sign-up flow to give your customers the flexibility to check their eligibility for a loan before starting the process.

How does it work?

The customer enters their desired loan amount and duration along with their self-declared financial information in your frontend. Based on this information, Solaris' automated credit scoring system evaluates the customer's credit risk and eligibility and immediately provides either an initial approval or a rejection.

In case of approval, the customer receives a non-binding loan offer, including the loan amount and term, interest rate, and monthly installment amount. This offer is only based on the self-declared information and the customer must start the application process to receive the final credit approval and binding offer.

In case of rejection in this stage, the customer receives either an adjusted loan offer (e.g., a lower loan amount or longer loan term) or a rejection.

POST Generate anonymous loan offer

This endpoint generates a non-binding anonymous loan offer for a customer based on their self-declared and unverified financial information. You must add the following mandatory fields in the request body of this endpoint:

  • requested_loan_term: The requested loan duration over which the loan will be repaid.
  • requested_loan_amount: The requested loan amount in EUR.
  • requested_emi: The requested equated monthly installment (EMI) in EUR the customer wants to pay each month to repay the loan principal and interest.
  • private_insurance_amount: The amount of private insurance fees the customer pays monthly in EUR.
  • number_of_dependents: The number of dependents (e.g., children) who depend on the customer's income.
  • net_income_amount: The customer's net income amount in EUR after tax deduction.
  • living_situation_amount: The customer's living monthly expenses, i.e., rent or mortgage, utilities, health insurance, etc.
  • living_situation: The customer's living situation. Possible values are LIVING_WITH_PARENTS, LIVING_IN_RENTED_HOUSE, or LIVING_IN_OWN_HOUSE.
  • existing_credit_repayment_excluding_mortgage: A field containing information about the customer's existing debt repayments (in EUR) (excluding mortgage payments).

Request URL

Copy
Copied
POST /v1/anonymous_consumer_loan_offers

Response example

The API call returns a non-binding loan offer, including the loan term, amount, monthly installment, and interest rate, as well as the loan decision, which can be either OFFERED or REJECTED.

attention

The loan decision returned by calling this endpoint is NOT final and is only based on the self-declared information. Additionally, the loan offer is NOT binding and the customer must initiate the loan application process to receive the final offer and approval.

Copy
Copied
{
  "offer": {
    "monthly_installment": {
      "value": 1000,
      "unit": "cents",
      "currency": "EUR"
    },
    "loan_term": 0,
    "loan_amount": {
      "value": 1000,
      "unit": "cents",
      "currency": "EUR"
    },
    "interest_rate": 0
  },
  "loan_decision": "OFFERED"
}

Click here to view the full API reference.

After the customer decides to apply for a loan, you must then collect the mandatory information from the customer on your frontend. Such information includes:

  • The mandatory personal information required to create a person resource in Step 1.
  • All the UTC timestamps of the customer's consent to the legal and regulatory requirements in System prerequisites.
  • The mandatory additional information required to create a consumer loan application resource in Step 3.

Step 1: Collect customer data and create person resource

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

What is a person resource?

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

API reference

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

Related webhook events

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

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

Note about branching

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

Example:

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

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

POST Create person

Call the following endpoint to create a person resource for your customer. Collect the following mandatory data points from the customer in your sign-up flow and add them to the request body:

note

The following data points are required for retail customers in Germany.

  • salutation (Check the appendix for possible enums)
  • first_name (including all middle names as printed on the ID document)
  • last_name (including all name parts as printed on the ID document)
  • birth_date
  • birth_city
  • birth_country (ISO 3166-1 alpha-2 codes
  • nationality (ISO 3166-1 alpha-2 codes
  • address (Street, Number, City, Postal Code, Country, State).
  • contact_address (OPTIONAL To be used only if the customer's current address is younger than two years.)
  • mobile_number The mobile number will be verified during the identification process.
  • iban (Only if the customer will be identified using the Bankident KYC method)
  • employment_status (Check the appendix for possible enums)
  • data_terms_signed_at (UTC timestamp)
  • terms_conditions_signed_at (UTC timestamp)
  • own_economic_interest_signed_at (UTC timestamp)
  • tax_information

    • tax_assessment (Indicates whether the customer files their taxes jointly or separately. Possible values are: NONE JOINT, or SEPARATE)
    • marital_status (Check the appendix for possible enums)
attention

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

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

Request URL

Copy
Copied
POST /v1/persons

Response example

The API returns a person object with a unique id, the person_id. You will need this id to append the person resource with additional information in the remaining steps of this guide.

Copy
Copied
{
  "id": "dc1a6812a14f6cc338cd084208535bcdcper",
  "salutation": "MR",
  "first_name": "Peter",
  "last_name": "Mustermann",
  "address": {
    "line_1": "Musterstrasse",
    "line_2": "Musterstrasse",
    "postal_code": "10409",
    "city": "Berlin",
    "country": "DE",
    "state": "BE"
  },
  "contact_address": {
    "line_1": "Musterstrasse",
    "line_2": "Musterstrasse",
    "postal_code": "10409",
    "city": "Berlin",
    "country": "DE",
    "state": "BE"
  },
  "mobile_number": "49301234567",
  "birth_date": "1972-12-24",
  "birth_city": "Berlin",
  "birth_country": "DE",
  "nationality": "DE",
  "employment_status": "EMPLOYED",
  "tax_information": {
    "tax_assessment": "SEPARATE",
    "marital_status": "MARRIED"
  },
  "terms_conditions_signed_at": "2017-01-01T00:00:00.000Z",
  "own_economic_interest_signed_at": "2017-01-01T00:00:00.000Z",
  "flagged_by_compliance": false,
  "screening_progress": "SCREENED_ACCEPTED",
  "data_terms_signed_at": "2017-01-01T00:00:00.000Z",
  "aml_follow_up_date": "2017-01-15",
  "aml_confirmed_on": "2017-01-30",
  "risk_classification_status": "NORMAL_RISK",
  "customer_vetting_status": "NO_MATCH",
}

Click here to view the full API reference


Step 2: Create customer credit record

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

What is a credit record?

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

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

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

API reference

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

POST Create a credit record for a retail customer

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

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

Request URL

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

Response example

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

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

GET Retrieve a customer's credit record

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

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

Request URL

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

Response example

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

Step 3: Create customer loan application

After collecting the mandatory personal information from the customer and creating a person resource, you must collect additional information from the customer related to the consumer loan application, and pass them to Solaris using the following endpoint.

POST Create consumer loan application

This endpoint creates a consumer loan application and assigns it to the person with the person_id specified in the request URL. The consumer loan application includes all the required information about the customer, such as their financial information, credit record, and loan information, which Solaris' credit scorer uses to initiate a series of credit checks.

Mandatory properties:

Add the following mandatory properties in the request body:

  • requested_loan_term: The requested loan duration over which the loan will be repaid.
  • requested_loan_amount: The requested loan amount in EUR.
  • requested_emi: The requested equated monthly installment (EMI) in EUR the customer wants to pay each month to repay the loan principal and interest.
  • repayment_day_of_month: The day of the month when the customer should pay the loan installment. Possible values are 1 and 15.
  • private_insurance_amount: The amount of private insurance fees the customer pays monthly in EUR.
  • number_of_dependents: The number of dependents (e.g., children) who depend on the customer's income.
  • net_income_amount: The customer's net income amount in EUR after tax deduction.
  • living_situation_amount: The customer's living monthly expenses, i.e., rent or mortgage, utilities, health insurance, etc.
  • living_situation: The customer's living situation. Possible values are LIVING_WITH_PARENTS, LIVING_IN_RENTED_HOUSE, or LIVING_IN_OWN_HOUSE.
  • existing_credit_repayment_excluding_mortgage: A field containing information about the customer's existing debt repayments (in EUR) (excluding mortgage payments).
  • moved_in_last_two_years: A field to indicate whether the customer has moved in the past two years.
  • credit_record_id: A unique ID of the customer's credit record resource created in the previous step.
  • loan_purpose: A text field to indicate the loan's purpose.
  • partner_reference_number: A field to include your internal reference number for the customer.

For loans related to purchased goods, the following fields are also mandatory:

  • cash_price: The cash price of the financed good (i.e., net price without financing interest).
  • seller: The name of the seller of the financed good.
  • financed_good: The financed good that was purchased using the loan.

Request URL

Copy
Copied
POST /v1/persons/{person_id}/consumer_loan_applications

Response example

The API call returns an object with a unique id (i.e., the application_id), including the application status and the remaining attributes, which will be populated during the application lifecycle.

This API call automatically triggers Solaris' automated retail credit scoring system, which scores the application and provides its decision on the loan application and specifies the customer's category.

Approved application

If Solaris' scorer approves the loan application, the application status changes to offered and the loan_decision value will change to OFFERED. The response body will include the binding offer for the loan, including the loan amount, term, interest rate and monthly installment.

Additionally, the field customer_category indicates the scorer internal flags. In case of approval, it'll be set to either GREEN (i.e., the application is approved without reservations) or AMBER (the application is approved, but additional verification is required).

Copy
Copied
{
    "offer": {
        "monthly_installment": {
            "value": 59709,
            "unit": "cents",
            "currency": "EUR"
        },
        "loan_term": 12,
        "loan_amount": {
            "value": 700000,
            "unit": "cents",
            "currency": "EUR"
        },
        "interest_rate": 0.0399,
        "id": "9b3147c5498b405d9402630bc308ad0ecofr",
        "effective_interest_rate": 0.0406,
        "approximate_total_loan_expenses": {
            "value": 716485,
            "unit": "cents",
            "currency": "EUR"
        }
    },
    "loan_decision": "OFFERED",
    "id": "108787ede6b743dcbe0c3398bc4a6ce8clap",
    "customer_category": "GREEN"

Rejected application

In case of rejection, the application status changes to rejected and the customer_category is set to RED.

Copy
Copied
{
    "offer": null,
    "loan_decision": "REJECTED",
    "id": "6c3e3f525abc4ad2a99c2d865c4d30faclap",
    "disposable_income": null,
    "customer_category": null
}

Click here to view the full API reference.

GET Retrieve consumer loan application

This endpoint retrieves a customer's consumer loan application. You can use this endpoint to track the application lifecycle through the status field in the response body. Additionally, subscribe to the webhook event CONSUMER_LOAN_APPLICATION to receive notifications whenever the application status changes.

Check the appendix for a list of possible values and descriptions for the status field. Additionally, check the application status flow here.

Request URL

Copy
Copied
GET /v1/persons/{person_id}/consumer_loan_applications/{application_id}

Response example

Copy
Copied
{
  "status_description": "The customer must complete the e-signing process",
  "status": "esign_pending",
  "signing_id": "7c63600ddddec4f2668893af39c1b814csig",
  "seller": "null",
  "payout_description": "string",
  "loan_id": "null",
  "id": "108787ede6b743dcbe0c3398bc4a6ce8clap",
  "financed_good": "null",
  "delayed_payout_strategy": "none",
  "cash_price": {
    "value": 1000,
    "unit": "cents",
    "currency": "EUR"
  },
  "approximate_total_loan_expenses": {
    "value": 1000,
    "unit": "cents",
    "currency": "EUR"
  }
}

Click here to view the full API reference.

POST Generate a subsidized offer for a consumer loan application (Optional)

This endpoint creates a subsidized loan offer with a reduced interest rate. You can call this endpoint and add the required interest rate in the request body to receive the new offer.

note

You have to pay Solaris the difference between the initial offered rate and the requested reduced one.

Request URL

Copy
Copied
POST /v1/persons/{person_id}/consumer_loan_applications/{consumer_loan_application_id}/offers/{offer_id}/subsidize

Response example

Copy
Copied
{
    "subsidized": true,
    "monthly_installment": {
        "value": 19446,
        "unit": "cents",
        "currency": "EUR"
    },
    "loan_term": 36,
    "loan_amount": {
        "value": 700000,
        "unit": "cents",
        "currency": "EUR"
    },
    "interest_rate": 0.0,
    "id": "abfe1f919a4841b9a40d8df78adc7dfdcofr",
    "effective_interest_rate": 0.0,
    "approximate_total_loan_expenses": {
        "value": 700000,
        "unit": "cents",
        "currency": "EUR"
    }
}

Click here to view the full API reference.


Step 4: Create account snapshot

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

What is an account snapshot?

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

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

API reference

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

POST Create an account snapshot for a customer

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

1. Account snapshot via FinTech systems

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

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

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

Request example

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

Response example

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

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

2. Account snapshot via Finreach

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

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

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

Request example

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

Response example

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

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

3. Account snapshot via partner

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

Request example

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

Response example

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

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

4. Account snapshot via Solaris

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

Request example

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

Response example

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

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

GET Retrieve a customer's account snapshot

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

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

Request URL

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

PUT Link customer account snapshot to consumer loan application

After creating an account snapshot, use this endpoint to link the customer's account snapshot to their existing credit line application. You must add the account_snapshot_id in the request body. Once linked, the application status changes to account_snapshot_verification.

Additionally, this action prompts the credit scoring system to perform the final verification and verify the self-declared financial information based on the customer's income, expenses, and recurring credit repayments.

After successful verification, the application status changes to approved. Alternatively, the status could change to underwriting, which means that manual underwriting must be performed on the application.

Request URL

Copy
Copied
PUT /v1/persons/{person_id}/consumer_loan_applications/{application_id}/account_snapshot
{
  "account_snapshot_id": "0a3f28733f9a4842842aae2804f80eb4snap"
}

Click here to view the full API reference.

PUT Upload the purchase contract related to the financed good (Optional)

If the loan will be used to finance the purchase of a specific asset, e.g., a car, upload the relevant asset purchase contract from the merchant and attach it to the loan application using the following endpoint.

Request URL

Copy
Copied
PUT /v1/persons/{person_id}/consumer_loan_applications/{application_id}/upload_purchase_contract

Click here to view the full API reference.


Step 5: Send SECCI form and loan contract

Before prompting the customer to sign the final contract of the loan, you must send the customer the Standard European Consumer Credit Information (SECCI) form. The SECCI form is a standardized credit form that includes the information related to a credit offer, such as creditor details, type of credit, amount, duration, interest rates, credit costs, etc.

In compliance with regulatory requirements, you must first send the customer the SECCI form to review and approve. Afterward, you can send them the final contract which they have to sign during the identification and e-signing process.

Implement the following endpoints to generate the SECCI form and final contract of a loan.

GET Retrieve the SECCI form of a loan

Call this endpoint to generate the SECCI form of the loan offer as a PDF. You must share this form to the customer before sending the final contract either via email or direct download through your app.

Request URL

Copy
Copied
GET /v1/persons/{person_id}/consumer_loan_applications/{application_id}/offers/{offer_id}/pre_contract

Click here to view the full API reference.

GET Retrieve final contract

After the customer reviews and approves the loan's SECCI form, call this endpoint to generate the final contract, which the customer must sign electronically during the identification process.

note

It's recommended to share the final contract with the customer via email or direct download prior to the identification process.

Request URL

Copy
Copied
GET /v1/persons/{person_id}/consumer_loan_applications/{application_id}/offers/{offer_id}/contract

Click here to view the full API reference.

attention

The customer must also sign an SDD mandate, which authorizes Solaris to debit the customer's account for the monthly installments. For more information about SDD mandates, check the SEPA DIRECT DEBIT GUIDE.


Step 6: Complete the customer identification and e-signing process

In the step, you must prompt the customer to complete the identification process, in which the customer will be identified in a video identification session through our provider IDnow. During this session, an identification agent will verify the customer's data against their identification documents, verify their mobile number, and collect the customer's qualified electronic signature (QES) on the loan contract, SDD mandate, and terms and conditions.

Call the following endpoints once the status of the consumer loan application changes to esign_pending.

note

This guide explains the integration process with video identification as the identification method. For an overview of other available KYC methods, check the customer KYC products overview page and consult with your Partner Manager.

GET Retrieve the signing ID

When the application status changes to esign_pending, it means that the identification and e-signing process has been triggered for the customer. You must call the GET Retrieve consumer loan application method to get the signing_id, which you'll need to retrieve the identification details.

Request URL

Copy
Copied
GET /v1/persons/{person_id}/consumer_loan_applications/{application_id}

Response example

Copy
Copied
OK 200
{
    "status_description": null,
    "status": "esign_pending",
    "signing_id": "1a087da3f32b1b3669ddd8a687435a94csig",
    "loan_id": null,
    "id": "1a1af712b01840ae8c417eb4c86b1942clap",
    "approximate_total_loan_expenses": {
        "value": 1200245,
        "unit": "cents",
        "currency": "EUR"
    }
}

GET Retrieve e-signing and identification details

Once you obtain the signing_id from the previous endpoint, call the following method to get the video identification details, such as the IDnow reference and URL.

Request URL

Copy
Copied
GET /v1/persons/{person_id}/signings/{signing_id}

Response example

The API call returns the identification details, such as the IDnow reference and url, to which you must redirect your customer to complete the identification process and the documents your customer must e-sign. The payload also includes the IDnow status.

note
  • For a list of possible values of the status of IDnow process and their descriptions, check the appendix.
  • Additionally, subscribe to the IDENTIFICATION webhook event to get IDnow status updates.
Copy
Copied
{
    "id": "97b07d67783856a08312f38bf7b7ef2ecidt",
    "reference": "TST-NGGWH",
    "url":"https://go.test.idnow.de/solarisbankesignsandbox/identifications/:id",
    "status": "pending",
    "completed_at": null,
    "method": "idnow",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "address": null,
    "documents": []
}

Click here to view the full API reference.

GET List the IDnow attempts of a person identification

This endpoint returns a list of IDnow attempts within a person identification. Each returned attempt includes the result, the reason (if the attempt was aborted), and the payload from the webhook related to that attempt.

Request URL

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

Click here to view the full API reference.

GET Retrieve the signed contracts

After successful identification and e-signing, call the following endpoint to retrieve the signed contracts.

Request URL

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

Response example

The API call returns the identification session details and status, as well as the signed documents.

note

The loan-related documents will have a document_type value of SIGNED_CONTRACT. There are two different types of contracts, , which can be distinguished by the last four characters of the document ID. The ldoc suffix indicates a signed SDD mandate, and the cdoc suffix indicates a signed contract (e.g., loan contract).

Copy
Copied
200 OK 
{
    "id": "56564cea82e8fdb75765c4a7c92693d1csig",
    "reference": "TST-TXTSH",
    "url": "https://go.test.idnow.de/solarisbankesignsandbox/identifications/24f3324d4ad0c023f6623050e750726ecidt/webcam",
    "state": "finished",
    "status": "finished",
    "completed_at": "2020-03-12T15:09:51.000Z",
    "method": "idnow",
    "identification_id": "24f3324d4ad0c023f6623050e750726ecidt",
    "documents": [
        {
            "id": "2b184a18bf7f2f945dfaac55c5ead1b1cdoc",
            "name": "24f3324d4ad0c023f6623050e750726ecidt_ldoc_signed.pdf",
            "content_type": "application/pdf",
            "document_type": "SIGNED_CONTRACT",
            "size": 116654,
            "customer_accessible": false,
            "created_at": "2020-03-12T15:10:15.000Z"
        },
        {
            "id": "ddffb4706e51ea2f9862ded706760a60cdoc",
            "name": "24f3324d4ad0c023f6623050e750726ecidt_cdoc_signed.pdf",
            "content_type": "application/pdf",
            "document_type": "SIGNED_CONTRACT",
            "size": 216502,
            "customer_accessible": false,
            "created_at": "2020-03-12T15:10:16.000Z"
        },
        {
            "id": "97ad2cc84dcc665c471675cb671b087ecdoc",
            "name": "24f3324d4ad0c023f6623050e750726ecidt.xml",
            "content_type": "application/xml",
            "document_type": "OTHER",
            "size": 2829,
            "customer_accessible": false,
            "created_at": "2020-03-12T15:10:16.000Z"
        },
        {
            "id": "681361f0f979393470c29e26f8d2faefcdoc",
            "name": "24f3324d4ad0c023f6623050e750726ecidt.xml.sig",
            "content_type": "application/pgp-signature",
            "document_type": "SIGNATURE",
            "size": 256,
            "customer_accessible": false,
            "created_at": "2020-03-12T15:10:16.000Z"
        },
        {
            "id": "137a53b807f1c2328c623c35711b32f3cdoc",
            "name": "24f3324d4ad0c023f6623050e750726ecidt.xml",
            "content_type": "application/xml",
            "document_type": "OTHER",
            "size": 2703,
            "customer_accessible": false,
            "created_at": "2020-03-12T15:10:17.000Z"
        },
        {
            "id": "6b7ba109120ad87ff88c293225463cd5cdoc",
            "name": "24f3324d4ad0c023f6623050e750726ecidt.xml.sig",
            "content_type": "application/pgp-signature",
            "document_type": "SIGNATURE",
            "size": 256,
            "customer_accessible": false,
            "created_at": "2020-03-12T15:10:17.000Z"
        }
    ]
}

GET Download a document

This endpoint downloads the file of the document with the id specified in the request URL. Call this endpoint to download the relevant signed documents to share them with the customer.

Request URL

Copy
Copied
GET /v1/persons/{person_id}/documents/{id}/file

Click here to view the full API reference

GET Retrieve the details of a successful identification

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

Request URL

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

Response example

Copy
Copied
200 OK
{
    "id": "39f5dbd387ed27ce90642210e2b3f124cidt",
    "reference": "TST-AUAQX",
    "url": "https://go.test.idnow.de/solarisbankesignsandbox/identifications/39f5dbd387ed27ce90642210e2b3f124cidt",
    "status": "successful",
    "completed_at": "2021-04-28T19:24:33.000Z",
    "method": "idnow",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "language": null,
    "address": null,
    "documents": [
      ....
              {
            "id": "afa9f317323f7477db6eeeaf569f6791cdoc",
            "name": "39f5dbd387ed27ce90642210e2b3f124cidt.pdf",
            "content_type": "application/pdf",
            "document_type": "KYC_REPORT",
            "size": 310550,
            "customer_accessible": false,
            "created_at": "2021-04-28T19:24:45.000Z"
        },
...
}

Click here to view the full API reference.


Step 7: Create the loan

After successful customer identification, screening and credit risk checks, you can create the loan for the customer.

Call the following endpoint when the status of the consumer loan application changes to loan_creation_pending.

PUT Pay out a customer loan

This endpoint pays out the loan to the customer's specified IBAN and assigns the loan to the customer's with the person_id and application_id specified in the request URL.

Request URL

Copy
Copied
PUT v1/persons/{person_id}/consumer_loan_applications/{application_id}/consumer_loan

Response example

The API call creates a loan resource and returns an id (i.e., the loan_id). The status of the consumer loan application should change to loan_created after calling this endpoint.

Copy
Copied
{
    "id": "6c8b5faf3c2d4a5682c5c80ef7382387cloa"
}

Click here to view the full API reference.

GET Retrieve consumer loan information

This endpoint returns the information related to a customer's loan, such as the loan status, account details, payouts, overdue amounts, interest rates, etc.

note
  • For a list of possible values of the loan status field and their descriptions, check the appendix.
  • Additionally, subscribe to the LOAN webhook event to receive updates about the loan status.

Request URL

Copy
Copied
GET /v1/loans/{loan_id}

Response example

Copy
Copied
{
    "total_loan_expenses": {
        "value": 756766,
        "unit": "cents",
        "currency": "EUR"
    },
    "term": 36,
    "status": "payout_issued",
    "repayment_plan_updated_at": "2021-06-16T10:22:39Z",
    "repayment_plan_created_at": "2021-06-16T10:22:39Z",
    "repayment_begin_date": "2021-08-02",
    "reference": null,
    "recipient_iban": "DE92370601930002130041",
    "purpose": null,
    "person_id": "15f69eb47080e0ada4cc5e9861774fb0cper",
    "payout_date": "2021-06-16",
    "overdue_amount": {
        "value": 0,
        "unit": "cents",
        "currency": "EUR"
    },
    "monthly_payment": {
        "value": 21021,
        "unit": "cents",
        "currency": "EUR"
    },
    "maturity_date": "2024-07-01",
    "loan_account_id": null,
    "loan_account_iban": "DE72110101014351836685",
    "interest_start_date": "2021-06-16",
    "interest_rate": 0.0499,
    "id": "c13447d659db4cdcb450b977f8f25c57cloa",
    "effective_interest_rate": 0.0511,
    "created_at": "2021-06-16T10:22:38",
    "billing_account_id": "1d0e52af0a62b4b44d8c54a87a7fc6a7cacc",
    "billing_account_iban": "DE72110101014351836685",
    "annual_percentage_rate": -0.301,
    "amount": {
        "value": 700000,
        "unit": "cents",
        "currency": "EUR"
    }
}

Click here to view the full API reference.


Step 8: Loan servicing

This step includes the different endpoints you need to integrate in your solution for servicing and maintaining consumer loans for your customers.

API reference

Visit the following link to find all the endpoints related to servicing and maintaining loans, including related properties and examples.

GET Retrieve a loan schedule

This endpoint retrieves the latest repayment schedule of the loan specified in the request URL. The call will return information about two components:

  • Loan balance
  • Loan installments

For detail descriptions about each field, check the API reference.

Request URL

Copy
Copied
GET /v1/loans/{loan_id}/repayment_schedule

Click here to view the full API reference.

GET Retrieve the repayment history of a loan

This endpoint retrieves the repayment history of the loan specified in the request URL. The call will return information about two components:

  • All SEPA Direct Debits (SDD) that were pulled from the customer's reference account tied to the loan.
  • All SEPA Credit Transfers (SCT) for any partial or full early repayments the customer have made (If applicable).

Request URL

Copy
Copied
GET /v1/loans/{loan_id}/repayment_history

Response example

Copy
Copied
{
  "repayment_history": [
    {
      "amount": {
        "currency": "EUR",
        "unit": "cents",
        "value": 1000
      },
      "date": "2020-07-03",
      "interest_amount": {
        "currency": "EUR",
        "unit": "cents",
        "value": 1000
      },
      "payout_amount": {
        "currency": "EUR",
        "unit": "cents",
        "value": 1000
      }
    }
  ]
}

Click here to view the full API reference.


What's next?

Congratulations! You've successfully integrated Solaris' Consumer Loans solution.

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

For an overview of Solaris' lending products, check the lending products overview page.

Useful resources

Check the following links for additional related guides and API reference documentation:


Appendix I: Enums

Consumer loan application status

Status Description
offered The application has passed the initial scoring step and was either scored as AMBER or GREEN.
account_snapshot_verification You must create an account snapshot for the customer and attach it to the application to trigger the credit scorer's final verification step.
underwriting The application is undergoing manual underwriting and credit risk checks.
approved The application has been approved.
esign_pending The identification and e-signing process has been triggered for the customer. The signing ID should be available when you call the GET Retrieve consumer loan application method.
screening_pending The customer's application is undergoing internal risk screening.
esign_failed The identification and e-signing process has failed. You need to trigger a new identification for the customer.
loan_creation_pending The customer identification, e-signing and screening have been completed successfully. A loan can be created and paid out to the customer.
loan_created A loan has been created and paid out to the customer.
rejected The application has been rejected.
deleted The application has been deleted.
expired The application has expired. An application becomes expired if either the linked credit record or account snapshot have exceeded their validity period. Call the relevant GET methods to check the status of a credit record or an account snapshot and create new ones and link them to the application.

Document types

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

Enum Description
ANNUAL_FINANCIAL_STATEMENT A business or a company's annual financial statement.
KYC_REPORT The KYC report generate after a successful customer identification.
ID_DOCUMENT An person's identification document, such as passport or ID.
SIGNATURE A signature example.
PICTURE A picture or a scanned document of any other type.
QES_DOCUMENT A document related to a Qualified Electronic Signature (QES).
SIGNED_CONTRACT A signed contract of any kind.
SIGNED_QES_DOCUMENT A document signed by a Qualified Electronic Signature (QES).
REGISTER_CHECK A register check.
REGISTER_EXTRACT A business or a company's commercial register excerpt or a similar document.
FOUNDATION_DOCUMENT The foundation document of a company or business.
SCHUFA_COMPACT_REPORT A compact SCHUFA report.
SCHUFA_GWG_REPORT A GWG SCHUFA report.
SCHUFA_FULL_REPORT A full SCHUFA report about a person.
SCHUFA_SHORT_REPORT A short SCHUFA report about a person.
CREDIT_AGENCY_REPORT A report issued by a credit agency.
SHARE_HOLDERS_AGREEMENT A business or a company's shareholders agreement.
SHAREHOLDERS_LIST A business or a company's shareholders list.
TRADING_LICENSE A business or a company's trading license.
TRANSPARENCY_REGISTER_EXTRACT An extract of a transparency register.
INVOICE An invoice of any kind.
OTHER Any other type of document.
VIDEO A video of any kind.
VAT_CERTIFICATE VAT registration certificate

Idnow status

The following table includes the possible values for the field status for the video identification process carried out by IDnow and the related description of each status.

Status Description
created The identification resource has been created for the customer.
pending The identification process has been triggered and the video identification URL and reference are generated. You must redirect the customer to the URL to complete the identification process with IDnow.
pending_successful The video identification was successful, but will be reviewed by the identification provider. You can already offer banking services to the customer at this stage. Once reviewed by the provider, the identification will be marked either as resolved positively (successful) or negatively (failed or canceled). A bank account will be automatically blocked if the identification is eventually marked as failed or canceled.
pending_failed The identification is currently under review. You cannot offer banking services to the customer at this stage. The identification might eventually turn to successful, but it is unlikely.
successful The video identification was successful. The customer can be onboarded. Please note that the customer's data might have been updated during the identification session.
aborted The customer aborted the identification process. The customer can still video-identify using the same URL.
canceled The provider canceled the video identification. The customer should video-identify again using the same URL.
failed The identification was unsuccessful. You *cannot onboard the customer or offer any banking services to them.

IDnow provides a reason for the canceled and aborted status. No reason can be disclosed for the final failed status.

Identification documents

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

List of passports with address

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

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

Appendix II: Application status flow

Diagram: Consumer loan application flow