Consumer Fronting Loans

This guide explains the integration process of Solaris' Fronting 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

Consumer fronting loans are currently only available for customers in Germany with a German bank account. Check the overview page for more details on the product specifications.

User journey

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

  • Apply for a loan on your frontend and provide the mandatory information.
  • Consent to Solaris' terms and conditions and the credit scoring process, which will be done in relation to their fronting loan application.
  • If their application is approved, the user must 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!

System prerequisites

Before integrating Solaris' Consumer Fronting 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.
  • IDENTIFICATION_ORIGINATION: Triggered when the identification origination status changes and the payload includes the signing_id and/or identification_id, needed to trigger the identification flow.
  • 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_FRONTING_APPLICATION: Triggered when the status of the consumer loan application changes.

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


Integration flow

The following sequence diagram gives an overview of the integration flow for the Consumer Fronting Loans solution:

Diagram: Consumer fronting loans flow

Integration steps

Integrate Solaris' Consumer Fronting Loans by completing the following steps:

User registration and loan application creation

  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 a credit record for the customer by completing Step 2.
  3. Create a consumer fronting loan application by completing Step 3.
  4. Create an account snapshot by completing Step 4.
  5. Upload the required documents and link them to the customer by completing 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 money flow

  1. Create the loan for the customer to trigger the payout by completing Step 7.
  2. Solaris transfers the loan amount from the settlement account to the customer's account via an external transfer.
  3. Solaris transfers the agio amount from the settlement account to your collection account.
  4. The full loan amount (agio + net loan amount) is settled from your collateral account and repaid to Solaris' settlement account.
  5. After all transfers are completed, the loan payout status changes to payout_issued, and the customer receives the loan amount.
note

After the loan payout, Solaris immediately sells the loan's contract and receivables back to you or other investors. Solaris doesn't perform any loan servicing, dunning, or collection.

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


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

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

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 consumer fronting 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 fronting loan application, and pass them to Solaris using the following endpoint.

POST Create consumer fronting loan application

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

Mandatory properties:

Add the following mandatory properties in the request body:

  • transaction_description: The transaction reference, which the recipient can see. Only use SEPA allowed characters in this field.
  • transaction_end_to_end_id: SEPA identifier (provided by the end customer who initiated the SEPA transaction), routed through the whole payment process. (string, max 35 characters without whitespace)
  • requested_loan_amount: The amount (in EUR) requested to be paid out to the recipient.
  • requested_loan_term: The duration over which the recipient will repay the loan.
  • requested_interest_rate: The interest rate applied to the loan.
  • repayment_day_of_month: The day of the month when the recipient should pay the loan installment.
  • private_insurance_amount: The private insurance amount the recipient pays monthly. Default to 0.
  • partner_snapshot_allowed: boolean field.
  • number_of_kids: The number of children under 18 the recipient has. It can be defaulted to 0.
  • net_income_amount: Object containing the recipient's net monthly income (in EUR).
  • recipient_name: The name of the loan recipient.
  • recipient_iban: The IBAN of the loan's recipient, to which the loan will be paid out.
  • loan_purpose: The reason for the loan application.
  • living_situation_amount: Object containing information about recipient's monthly expenditures for living (e.g., rent/mortgage).
  • living_situation: A field that describes how the recipient lives at their current address. Possible values are LIVING_WITH_PARENTS, LIVING_IN_RENTED_HOUSE, and LIVING_IN_OWN_HOUSE.
  • existing_credit_repayment_excluding_mortgage: Object containing information about existing debt repayments (excluding mortgage payments).
  • credit_record_id: The unique ID of a credit record created for the customer.

Request URL

Copy
Copied
POST /v1/consumers/persons/{person_id}/fronting_loan_applications

Response example

The API call returns an object with a unique id for the consumer fronting loan application, including the application status and the remaining attributes, which will be populated during the application lifecycle.

Copy
Copied
{
    "account_snapshot_id": null,
    "agio": 0.0,
    "credit_record_id": "fbb7d15fa4c54ba0b077592665ef04a4ccrd",
    "decision": "OFFERED",
    "id": "bed381b116074b948f5c7619c60b53cacfla",
    "identification_origination_id": null,
    "loan_purpose": "string",
    "partner_id": "f8e62eba7f3c4913ed469c549a2ba606cpar",
    "partner_reference_number": "string",
    "partner_score": "string",
    "partner_snapshot_allowed": true,
    "person_id": "c32a42cbf2ed71fff0c29303b6efff2bcper",
    "recipient_iban": "DE92370601930002130041",
    "recipient_name": "Max Mustermann",
    "requested_interest_rate": 0.04,
    "requested_loan_amount": {
        "currency": "EUR",
        "unit": "cents",
        "value": 10000
    },
    "requested_loan_term": 6,
    "status": "account_snapshot_pending",
    "transaction_description": "string"
}

Click here to view the full API reference

note
  • If the field partner_snapshot_allowed is set to true, the application status transitions to account_snapshot_pending, and you have to create an account snapshot for the customer and link it to their application as explained in Step 4.
  • If the field partner_snapshot_allowed is set to false, the application status transitions to binding_offer_scoring_pending, and you have to continue the flow from Step 5.

GET Retrieve consumer fronting loan application

This endpoint returns the current status and details of an existing consumer fronting loan application. For a list of possible values of the application status and their descriptions, check the appendix.

Additionally, subscribe to the webhook event CONSUMER_FRONTING_APPLICATION to receive status updates on the application.

Request URL

Copy
Copied
GET /v1/consumers/persons/{person_id}/fronting_loan_applications/{application_id}

Response example

Copy
Copied
{
    "account_snapshot_id": null,
    "agio": 0.0,
    "credit_record_id": "fbb7d15fa4c54ba0b077592665ef04a4ccrd",
    "decision": "OFFERED",
    "effective_interest_rate": 0.04,
    "id": "bed381b116074b948f5c7619c60b53cacfla",
    "identification_origination_id": null,
    "loan_purpose": "Buying a car",
    "partner_id": "4415764dc7723163991c8d6cef1db204cpar",
    "partner_reference_number": "string",
    "partner_score": "string",
    "partner_snapshot_allowed": true,
    "payout_date": "2019-08-24",
    "person_id": "b7314462ab8caddb41f2d6b48228fdcecper",
    "recipient_iban": "DE92370601930002130041",
    "recipient_name": "string",
    "requested_interest_rate": 0.04,
    "requested_loan_amount": {
        "currency": "EUR",
        "unit": "cents",
        "value": 1000
    },
    "requested_loan_term": 6,
    "status": "account_snapshot_pending",
    "total_interest_amount": {
        "currency": "EUR",
        "unit": "cents",
        "value": 1000
    },
    "total_principle_amount": {
        "currency": "EUR",
        "unit": "cents",
        "value": 1000
    },
    "total_repaid_loan_amount": {
        "currency": "EUR",
        "unit": "cents",
        "value": 1000
    },
    "transaction_description": "Transaction description",
    "transaction_end_to_end_id": "string"
}

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 only if the field partner_snapshot_allowed is set to true.

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 account snapshot to consumer fronting 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.

After the account snapshot is linked to the loan application, the application status changes to scoring_pending.

Request example

Copy
Copied
PUT /v1/consumers/persons/{person_id}/fronting_loan_applications/{application_id}/account_snapshot

{
  "account_snapshot_id": "0a3f28733f9a4842842aae2804f80eb4snap"
}

Click here to view the full API reference


Step 5: Upload required documents and link them to the loan application

In this step, you must upload the required documents and link them to the consumer fronting loan application. The necessary documents are agreed upon with Solaris' credit risks team and legal team during the project phase.

note

You have to make a separate API call for each document.

API reference

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

POST Create document

This endpoint uploads a document and links it to the person with the person_id specified in the request URL.

You have to add the following properties to the request body:

  • document_type: The document type. For a list of possible values, check the appendices section.
  • file: The file to be uploaded.
note

The request body of this endpoint is a multipart/form-data content type and parameters are transmitted as form-data and not as a raw JSON string.

Request URL

Copy
Copied
POST /v1/persons/{person_id}/documents
# request parameters
..
Content-Disposition: form-data; name="file"; filename="filename.png"
Content-Type: image/png
..
Content-Disposition: form-data; name="document_type"

OTHER
..

Response example

The API call returns an object with a unique id, which is the document_id you would need to attach the document to other resources, such as identification or lending-related application.

Copy
Copied
{
  "id": "69ec2a9d8dbaf5ea1b13124098a34ea3cdoc",
  "name": "signed_contract.png",
  "content_type": "image/png",
  "document_type": "SIGNED_CONTRACT",
  "size": "string",
  "customer_accessible": false,
  "created_at": "2019-09-10T07:58:00.908Z",
  "deleted_at": "string"
}

Click here to view the full API reference


Scoring

After linking the required resources to the fronting loan application, Solaris' credit scoring system analyzes the application data and other 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.

Acceptance

If the application passes the credit scoring process, the application status transitions to offered. Afterward, the customer must complete the identification (KYC) process for the loan to be fully accepted.

If the identification is not required, the application status directly transitions to accepted, and you can trigger the loan payout process.

In both cases, after the customer passes the initial credit check, generate the loan offer and send it to the customer to collect their acceptance or rejection of the loan agreement.

Rejection

If the application fails the credit scoring process, notify the customer of the rejection.


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.

POST Create identification origination

This endpoint creates a customer identification for the purpose of issuing the loan. You must specify the identification method to be used. The default value is idnow.

Additionally, this API call triggers the e-signing process, in which the customer must provide a qualified electronic signature (QES) on the loan agreement during the video identification process.

Request example

Copy
Copied
POST /v1/identification_origination/persons/{person_id}/identifications
{
  "method": "idnow",
  "additional_documents": [
    {
      "signature_position": {
        "mysignature1": {
          "position": {
            "width": 100,
            "page": "1",
            "left": 20,
            "height": 20,
            "bottom": 10
          }
        }
      },
      "identifier": "XXXX",  //agreed document identifier(e.g. for contract etc.)
      "document_id": "69ec2a9d8dbaf5ea1b13124098a34ea3cdoc"
    }
  ]
}

Response example

The API call returns an object with a unique identification_origination_id, which you will need to link the identification to the customer's fronting loan application, as well as the identification origination status, set initially to identification_trigger_pending.

Copy
Copied
{
    "esigning_id": null,
    "identification_id": null,
    "identification_origination_id": "589e12da53154010ad180894acbe07ebio",
    "status": "identification_trigger_pending",
    "status_description": null
}

Click here to view the full API reference

PUT Link identification origination to loan application

This endpoint links the identification origination resource created for a customer to their fronting loan application. You must add the person_id and the application_id in the request URL and add the following properties in the request body:

  • identification_origination_id: The unique ID of the identification origination resource, created after calling the previous endpoint.

After linking the identification to the loan application, the application status transitions to identification_trigger_pending.

Request example

Copy
Copied
PUT /v1/consumers/persons/{person_id}/fronting_loan_applications/{application_id}/identification 
{
  "identification_origination_id": "589e12da53154010ad180894acbe07ebio"
}

Click here to view the full API reference

GET Retrieve identification origination

This endpoint retrieves an existing identification origination for a specific customer. You must add the person_id and the identification_origination_id in the request URL.

Call this endpoint to check the identification_origination_status and get the esigning_id and the identification_id required to prompt your customer to complete the e-signing and the video identification processes.

Additionally, subscribe to the webhook event IDENTIFICATION_ORIGINATIONand you'll receive a notification containing the esigning_id and the identification_id once they have been created.

Once the identification flow is created, the loan application status transitions to identification_pending.

note
  • For a list of possible values of the status of the identification origination and their descriptions, check the appendix.

Request URL

Copy
Copied
GET /v1/identification_origination/persons/{person_id}/identifications/{identification_origination_id}

Response example

Copy
Copied
200 - OK
{
    "esigning_id": "5ade4e499b299c299be2987ad597c42ecsig",
    "identification_id": "17905779039e75dce7bf8d68f3184942cidt",
    "identification_origination_id": "589e12da53154010ad180894acbe07ebio",
    "status": "esign_pending",
    "status_description": "Waiting for signing process to finish"
}

Click here to view the full API reference

GET Retrieve identification details

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

Request URL

Copy
Copied
GET /v1/persons/{person_id}/signings/{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": "5ade4e499b299c299be2987ad597c42ecsig",
    "reference": "TST-ZQWGG",
    "url": "https://go.test.idnow.de/solarisbankesignsandbox/identifications/17905779039e75dce7bf8d68f3184942cidt/webcam",
    "state": "pending",
    "status": "pending",
    "completed_at": null,
    "method": "idnow",
    "identification_id": "17905779039e75dce7bf8d68f3184942cidt",
    "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 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": "9dfe2f4edaa67138be0c0c1cd3a7d849cidt",
  "reference": "TST-ELCCJ",
  "url": "https://go.test.idnow.de/",
  "status": "successful",
  "completed_at": "2021-09-14T18:18:28.000Z",
  "method": "idnow",
  "proof_of_address_type": "GAS_BILL",
  "proof_of_address_issued_at": "2021-12-03",
  "language": "EN",
  "person_id": "992de312a545bb24a88ddbf57ae8b1ffcper",
  "address": {
    "line_1": "BERLINER STR. 45",
    "line_2": "Erste Etage",
    "postal_code": "14169",
    "city": "Berlin",
    "country": "DE",
    "state": "BE"
  },
  "documents": [
    {
      "id": "448b75fa1c57eecda41d91c66c22faa6cdoc",
      "name": "file1.pdf",
      "content_type": "application/json",
      "document_type": "KYC_REPORT",
      "size": 803580
    },
    {
      "id": "94eb22a9311be9a1fbb698c448b0b337cdoc",
      "name": "file2.jpg",
      "content_type": "image/jpeg",
      "document_type": "SIGNATURE",
      "size": 25349
    }
  ],
  "failure_reason": "string",
  "iban": "DE11010101010101010100",
  "authorization_expires_at": "string",
  "confirmation_expires_at": "string",
  "provider_status_code": 1000
}

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

Using the document IDs, you can download the files using the previous GET Download document endpoint.


Step 7: Create the loan

After the identification and e-signing reaches the status successful, trigger the loan payout by calling the following endpoint. The fronting application status must be set to accepted before you can trigger the loan payout.

POST Trigger loan payout

This endpoint triggers the loan payout process to the respective customer. You must add the following properties in the request body:

  • settlement_account_iban: Solaris' account, from which the loan amount is transferred to the customer's account.

Request URL

Copy
Copied
POST /v1/consumers/persons/{person_id}/fronting_loan_applications/{application_id}/payout
{
  "settlement_account_iban": "DE07110101014503906016"
}

Response example

The API call returns an object with a unique ID, the loan_id. The payload contains the loan details, the IBANs of related accounts, and the status of the loan payout, which is set to payout_pending after calling this endpoint.

Copy
Copied
{
    "agio": 0.00,
    "amount": {
        "currency": "EUR",
        "unit": "cents",
        "value": 515000
    },
    "application_id": "XXXXcfla",
    "collateral_account_iban": "DEXXXXX", 
    "collection_account_iban": "DEXXXXX", 
    "duration": 6,
    "id": "XXXXXXflo",
    "recipient_iban": "DEXXXX", 
    "recipient_name": "string",
    "requested_interest_rate": 0.04,
    "settlement_account_iban": "DE07110101014503906016",
    "status": "payout_pending"
}

Click here to view the full API reference

GET Retrieve consumer fronting loan

This endpoint returns all the details and status of an existing consumer fronting loan assigned to the person with the given person_id in the request URL.

note
  • For a list of possible values of the status of the loan payout and their descriptions, check the appendix.

Request URL

Copy
Copied
GET /v1/consumers/persons/{person_id}/fronting_loans/{loan_id}

Response example

Copy
Copied
{
  "status": "string",
  "settlement_account_iban": "string",
  "requested_interest_rate": 0,
  "recipient_name": "string",
  "recipient_iban": "string",
  "id": "string",
  "duration": 6,
  "collection_account_iban": "string",
  "collateral_account_iban": "string",
  "application_id": "string",
  "amount": {
    "value": 10000,
    "unit": "cents",
    "currency": "EUR"
  },
  "agio": 0
}

Click here to view the full API reference

Money flow

After triggering the loan payout, you have to complete the money flow described below.

Accounts

The money moves between three different accounts:

  • Settlement account: A Solaris account from which the loan amount is transferred to the customer's account.
  • Collateral account: A Solaris account, but under your name.
  • Collection account: Your account.

Process

After triggering the loan payout process, you must ensure that all transfers are executed to the relevant account:

note

The loan payout includes the loan net amount and the credit commission amount (agio) if applicable.

After you trigger the loan payout for the customer, the money flow goes as follows:

  1. Solaris transfers the loan amount from the settlement account to the customer account via an external transfer.
  2. If applicable, Solaris transfers the agio amount from the settlement account to your collection account.
  3. Solaris sells back the loan agreement and receivables to you or other investors, who take care of the rest of the loan lifecycle
attention

The loan payout amount must equal the minimum balance of the collateral account. Otherwise, the payout will fail.

After all the transfers are executed successfully, the loan payout status changes to payout_issued. The customer should receive the loan amount to their account.


What's next?

Congratulations! You've successfully integrated Solaris' Consumer Fronting 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 fronting loan application status

The following table includes the enums for the field status and their descriptions in the consumer fronting loan application resource.

Status Description
account_snapshot_pending If the field account_snapshot_allowed is set to true, the status is set to account_snapshot_pendingupon creating the fronting loan application and until you link an account snapshot to the application.
scoring_pending An account snapshot has been linked to the application, triggering the credit scoring process.
offered The fronting loan application has passed the credit scoring process, and customer identification is still to be completed.
identification_trigger_pending The customer identification resource (e.g., identification origination) has been linked to the fronting loan application.
identification_pending The customer identification flow has been triggered, and the customer must complete it within the validity period.
accepted The customer credit scoring and/or identification process have been completed successfully, and the fronting loan application is approved.
rejected The customer credit scoring and/or identification has failed, and the fronting loan application is rejected.
expired The fronting loan application has expired due to an expired credit record or account snapshot. Use the GET methods for credit record and account snapshot to inform yourself about the status, create new resources, and link them to the fronting loan application in case of expiration.
loan_created The loan payout process has been triggered.
binding_offer_scording_pending If the field account_snapshot_allowed is set to false, the status is set to binding_offer_scording_pending upon creating the fronting loan application. Afterward, the application flow will reach either offered and the rest of the identification-related statuses or directly to the decision (if identification is skipped) to either accepted or rejected.

Consumer fronting loan payout status

The following table includes the enums for the field status and their descriptions for the consumer fronting loan payout.

Status Description
payout_pending The consumer loan payout has been triggered.
payout_issued All transfers to the relevant accounts are completed, and the loan is paid out to the customer.

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

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

Identification origination status

Status Description
identification_trigger_pending The identification origination resource has been created, which triggers both the video identification and e-signing process.
esign_pending The e-signing process has been generated. You have to call the GET identification origination method to get the identification_id and the esigning_id you need to prompt your customers to complete both processes.
identification_completion_pending The customer's identification process must be completed. You have to obtain the video identification URL by calling the GET signing method using the esigning_id and redirect your customer to complete the video identification with IDnow.
screening_pending The customer has completed the video identification and e-signing and Solaris is performing the customer's screening and risk checks.
failed The customer's e-signing or identification or risk screening has failed.
completed The customer identification process is successful.
expired The customer identification has expired, i.e., the customer has failed to complete the required identification steps within the specifed period.

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.