Consumer Fronting Loans

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Introduction

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.

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:

1. Application: The customer applies for a loan on your frontend and provides the mandatory information.
2. Consent: The customer consents to Solaris' terms and conditions and the credit scoring process (SCHUFA).
3. Approval: If the application is approved, the customer must complete the identification process and sign the loan contract.
4. Payout: The loan amount will be credited to their account immediately.

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. The Legal and compliance screens guide contains step-by-step instructions on how to create these screens and what they must contain.

The following screens are required to onboard B2C customers for lending standalone products:

1. Terms and Conditions
2. Customer information
3. Economic interest

Consent timestamps

You must record the customer's consent on each screen as a UTC timestamp (e.g., 2019-01-01T00:00:00Z) and pass it to Solaris in the following fields:

• Solaris Terms and Conditions: terms_conditions_signed_at
• Data Processing Terms: data_terms_signed_at
• Economic Interest Declaration: own_economic_interest_signed_at

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.
• 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.
• ACCOUNT_SNAPSHOT: The status of a customer's account snapshot has changed.
• CONSUMER_FRONTING_APPLICATION: Triggered when the status of the consumer loan application changes.

Integration flow

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

Integration steps

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

Mandatory features

You must integrate all mandatory features for Consumer Fronting highlighted in the Onboarding requirements guide before going live.

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, pass all the data points to Solaris by creating a person resource to represent your customer.

API reference

For a complete list of endpoints, properties, and examples related to the person resource, visit the following links:

• Person resource API reference
  • POST Create person
  • GET Retrieve a person
  • PATCH Update person

Related webhook events

• PERSON_CHANGED
• PERSON_DELETED

POST Create person

Create a person resource to represent your customer. You must include the following data points in the request body to satisfy the requirements for German Consumer Loans.

Mandatory fields for retail customers in Germany:

• salutation
• first_name
• last_name
• email
• mobile_number
• birth_date
• birth_city
• birth_country
• nationality
• employment_status
• address:
  • line_1
  • line_2 (optional)
  • postal_code
  • city
  • country
• tax_information:
  • marital_status
• terms_conditions_signed_at
• data_terms_signed_at
• own_economic_interest_signed_at

Request URL

POST /v1/persons

• API Reference: Create person

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 mandatory for Lending integrations, as it is used for credit scoring to determine the customer's creditworthiness and eligibility.

Create a credit record

To create a credit record, you must choose a source in the request body:

1. source: solarisBank (Automated) Solaris retrieves the customer's record directly from SCHUFA. This is the standard recommended process.

2. source: partner (Manual Upload) You collect the credit record manually from SCHUFA or third-party providers and upload it to Solaris.

   • Requirement: You must Base64-encode the file and pass the content in the file field.

Endpoints:

Depending on your customer type, use one of the following endpoints:

Retail Customers

POST /v1/persons/{person_id}/credit_records

• API Reference: Create retail credit record

Freelancers

POST /v1/freelancers/persons/{person_id}/credit_records

• API Reference: Create freelancer credit record

GET Retrieve a credit record

Call this endpoint to check the status and validity of an existing credit record.

Request URL

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

• API Reference: Retrieve credit record

Step 3: Create consumer fronting loan application

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

POST Create consumer fronting loan application

This endpoint creates a consumer fronting loan application. The application includes all required information (applicant info, credit record, loan terms, IBAN) which Solaris' credit scorer uses to initiate credit checks.

Mandatory Properties:

• SEPA References:

  • transaction_description: Reference visible to the recipient. Constraint: SEPA characters only.
  • transaction_end_to_end_id: ID routed through the payment process. Constraint: String, max 35 characters, no whitespace.

• Loan Terms:

  • requested_loan_amount, requested_loan_term, requested_interest_rate.
  • repayment_day_of_month: Day for monthly installments.
  • loan_purpose: Reason for the application.

• Recipient Details:

  • recipient_name & recipient_iban: Payout destination.
  • partner_snapshot_allowed: (boolean) Determines if a partner snapshot is required.

• Financial & Scoring Data:

  • net_income_amount: Monthly net income object.
  • living_situation: Housing status (e.g., LIVING_IN_RENTED_HOUSE).
  • living_situation_amount: Monthly housing costs object.
  • existing_credit_repayment_excluding_mortgage: Other debt obligations object.
  • private_insurance_amount: Monthly insurance costs (Default: 0).
  • number_of_kids: Children under 18 (Default: 0).
  • credit_record_id: The ID of the credit record created for the customer.

Request URL

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

Response example

{
  "account_snapshot_id": null,
  "agio": 0,
  "credit_record_id": "fbb7d15fa4c54ba0b077592665ef04a4ccrd",
  "decision": "OFFERED",
  "id": "bed381b116074b948f5c7619c60b53cacfla",
  "partner_snapshot_allowed": true,
  "person_id": "c32a42cbf2ed71fff0c29303b6efff2bcper",
  "recipient_iban": "DE92370601930002130041",
  "requested_interest_rate": 0.04,
  "requested_loan_amount": {
    "currency": "EUR",
    "unit": "cents",
    "value": 10000
  },
  "requested_loan_term": 6,
  "status": "account_snapshot_pending"
}

• API Reference: Create application

GET Retrieve consumer fronting loan application

This endpoint returns the current status and details of an existing consumer fronting loan application.

Request URL

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

• API Reference: Retrieve application

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 specific period. It is mandatory for Lending integrations, as it is used for credit scoring to verify the customer's financial data.

Create an account snapshot

Call the endpoint below to create a snapshot. You must specify the source field to determine the integration method.

Request URL

POST /v1/persons/{person_id}/account_snapshots

• API Reference: Create snapshot

Method 1: FinTecSystems (FTS)

Use this method to integrate the FTS wizard.

1. Integrate the FTS wizard in your solution (see FTS Documentation).
2. Call the endpoint with source: FIN_TECH_SYSTEMS. Optionally, include the iban.
3. Use the returned wizard_session_key to initialize the FTS wizard.
4. The customer enters their credentials in the wizard.

Request:

{
  "source": "FIN_TECH_SYSTEMS"
}

Response:

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

Method 2: Finreach

Use this method to integrate the FinX widget.

1. Integrate the FinX widget (see FinX Documentation).
2. Call the endpoint with source: FINREACH.
3. Redirect the customer to the URL provided in the location field.

Request:

{
  "source": "FINREACH"
}

Response:

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

Method 3: Partner (Manual Upload)

Use this method if you have your own connection to a third-party provider and want to upload the data directly.

• Set source to PARTNER.
• Include the full data structure in snapshot_data.

Request:

{
  "source": "PARTNER",
  "snapshot_data": {
    "account": {
      "bank_name": "",
      "bic": "",
      "country_id": "",
      "description": "",
      "holder": "John Smith",
      "iban": "DE92370601930002130041",
      "joint_account": false
    },
    "balance": {
      "balance": 3720.2,
      "currency": "EUR",
      "date": "2022-02-03",
      "limit": 0
    },
    "date": "2022-02-03",
    "days": 90,
    "turnovers": [
      { … }
    ]
  }
}

Method 4: Solaris (Internal)

Use this method if the customer already has a Solaris account.

• Set source to SOLARISBANK.
• Include the account_id of the Solaris account.

Request:

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

Response:

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

GET Retrieve account snapshot

Call this endpoint to check the status and validity of an existing snapshot.

Request URL

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

• API Reference: Retrieve snapshot

PUT Link account snapshot to consumer fronting loan application

After creating an account snapshot, use this endpoint to link it to the application. You must add the account_snapshot_id in the request body.

After linking, the application status changes to scoring_pending.

Request example

{
  "account_snapshot_id": "0a3f28733f9a4842842aae2804f80eb4snap"
}

• API Reference: Link snapshot

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 (e.g., proof of income).

API reference

For a complete list of endpoints, properties, and examples related to the person document resource, visit the following links:

• Person documents API reference
  • POST Create a document for a person
  • GET Retrieve metadata about a document
  • GET Download a document
  • GET Index a person's documents
  • PATCH Update document attributes
  • DELETE Delete a document

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

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

Click here to view the full API reference

Scoring

After linking the required resources, Solaris' credit scoring system analyzes the application data, financial information, and transaction history to assess creditworthiness.

Outcomes:

1. Identification Required (Standard):

   • If the application passes scoring, the status transitions to offered.
   • Proceed to Step 6.

2. Identification Skipped (Existing Customer):

   • If the customer is already identified (and no new identification is required), the status directly transitions to accepted.
   • You can skip Step 6 and trigger the loan payout immediately in Step 7.

3. Rejected:

   • If the application fails scoring, the status transitions to rejected.
   • Action: Notify the customer of the rejection.

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

In this step, you must prompt the customer to complete the identification process via a video identification session (IDnow). During this session, an agent will verify the customer's data 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. It also triggers the e-signing process for the QES.

Request example

{
  "method": "idnow",
  "additional_documents": [
    {
      "signature_position": { … },
      "identifier": "XXXX",
      "document_id": "69ec2a9d8dbaf5ea1b13124098a34ea3cdoc"
    }
  ]
}

Response: Returns an identification_origination_id. Status is initially identification_trigger_pending.

• API Reference: Create origination

PUT Link identification origination to loan application

Link the identification resource to the loan application. The status transitions to identification_trigger_pending.

Request example

{
  "identification_origination_id": "589e12da53154010ad180894acbe07ebio"
}

• API Reference: Link identification

GET Retrieve identification origination

Call this endpoint to check the identification_origination_status and get the esigning_id and identification_id required to prompt your customer to complete the process.

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

Request URL

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

• API Reference: Retrieve origination

GET Retrieve identification details

Use the identification_id to get the video identification details, such as the IDnow reference and url. Redirect the customer to this URL.

Request URL

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

• API Reference: Retrieve details

GET Retrieve the signed contracts

After successful identification (status: successful), call this endpoint to retrieve the signed documents.

Request URL

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

Step 7: Create the loan

After the identification and e-signing reaches the status successful (or if ID was skipped), trigger the loan payout. The fronting application status must be set to accepted before you can proceed.

POST Trigger loan payout

This endpoint triggers the transfer from the Solaris settlement account to the customer.

Request example

{
  "settlement_account_iban": "DE07110101014503906016"
}

Response: Returns loan_id and status payout_pending.

• API Reference: Trigger payout

GET Retrieve consumer fronting loan

Retrieve loan details and track the CONSUMER_FRONTING_LOAN_PAYOUT webhook.

Request URL

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

• API Reference: Retrieve loan

Money flow

After triggering payout, you must execute the following transfers:

1. Payout: Solaris transfers funds from the Settlement Account -> Customer Account.
2. Agio (If applicable): Solaris transfers the agio (commission) from the Settlement Account -> Your Collection Account.
3. Settlement: You must transfer the full loan amount (Net + Agio) from Your Collateral Account -> Solaris Settlement Account.
4. Sale: Solaris sells back the loan agreement and receivables to you (or other investors).

When all transfers complete, the status changes to payout_issued.

Related resources

• Consumer Fronting API Reference
• Identification Origination API Reference
• Video Identification Guide
• SEPA Transfers Guide

Appendix I: Enums

Consumer fronting loan application status

Consumer fronting loan payout status

Document types

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

Identification documents

1. List of accepted passports for video identification via IDnow: here
2. List of accepted passports for postIdent: here
3. Search for an identification document: here

List of passports with address

The following table lists all ID types that include the bearer's address, which you can use to perform identification without having to provide a proof of address document.

Identification origination status

IDnow status

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

IDnow provides a reason whenever the identification has a canceled or aborted status. No reason is disclosed for the final failed status.