Consumer 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 for the Solaris Consumer Loans product for retail customers as a standalone solution. It covers the mandatory information you must collect and the endpoints and webhooks required for integration.

Product specifications

The Solaris Consumer Loans product enables you to offer loans to retail customers through an efficient workflow. Using the API and an automated credit scoring system, you can create loan applications, identify customers, issue payouts, and service consumer loans.

Solaris loans are versatile and customizable. The standard offering includes loan amounts ranging from EUR 1,000 to 50,000 and terms from 12 to 84 months. You can choose between a standard loan or a loan tied to financing the purchase of goods.

Credit scoring

Solaris uses an automated retail credit scoring system to make informed credit decisions. The scorer analyzes financial information, credit data, transaction history, and outstanding loans to assess creditworthiness, risk level, and eligibility.

Based on checks performed throughout the application lifecycle, the scorer estimates the probability of default (PD) and determines whether to offer a loan, including the specific amount, term, and interest rate.

Interaction with the consumer loan service

The consumer loan service handles requests and collects applicant information, such as self-declared financial data, credit records, and account snapshots. The scorer provides decisions based on the information provided at each stage:

• Anonymous offer: Evaluates self-declared information provided during the non-binding offer request. Returns an immediate decision. (Only applies if you implement the anonymous offer endpoint).
• Binding offer: Decides whether to make a binding offer by analyzing the loan application and external credit records (e.g., SCHUFA).
• Verification: Uses the account snapshot to verify financial information. This is the final check before the final decision. This step can be skipped based on your configuration.

System prerequisites

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

Integration overview

The following sequence diagram outlines the integration flow for the Consumer Loans solution:

Integrate Solaris Consumer Loans by completing the following steps:

Webhooks

Subscribe to the following webhook events to automate your processes:

• ACCOUNT_SNAPSHOT
• CONSUMER_LOAN_APPLICATION
• IDENTIFICATION
• PERSON_CHANGED
• PERSON_DELETED
• PERSON_MOBILE_NUMBER_CREATED
• PERSON_MOBILE_NUMBER_DELETED
• LOAN

Mandatory features

Integrate all mandatory features for B2C Loans highlighted in the Onboarding requirements guide before going live.

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

You may offer customers a non-binding anonymous loan offer before they provide personal data or start the application. This optional step allows customers to check eligibility early.

How it works

The customer enters their desired loan amount, duration, and self-declared financial information. The scoring system evaluates eligibility and provides an initial approval or rejection.

• Approval: Returns a non-binding offer (amount, term, interest rate, monthly installment).
• Rejection: Returns a rejection or an adjusted offer (e.g., lower amount).

POST Generate anonymous loan offer

Call this endpoint to generate the offer.

Mandatory fields: The following fields are strictly required by the schema:

• requested_loan_term
• requested_loan_amount
• number_of_dependents
• net_income_amount
• living_situation_amount
• living_situation
• private_insurance_amount

Optional fields: Include these if available to improve scoring accuracy:

• requested_emi
• existing_credit_repayment_excluding_mortgage

Request URL

POST /v1/anonymous_consumer_loan_offers

Response

The API returns a loan_decision (OFFERED or REJECTED) and the offer details.

• API Reference: Create anonymous loan offer

Step 2: Collect customer data and create person resource

Collect the mandatory customer data, including timestamps for the legal and compliance screens. Create a person resource to send this data to Solaris.

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

PATCH update person

This endpoint updates one or more properties on a person resource. You can only update the following properties using this endpoint:

• title
• salutation
• address (line_1, line_2, postal_code, city, state, country)
• contact_address (line_1, line_2, postal_code, city, state, country)
• employment_status
• job_title
• email
• tax_information (tax_assessment, marital_status)
• fatca_relevant
• fatca_crs_confirmed_at
• business_purpose
• industry
• industry_key
• own_economic_interest_signed_at
• aml_confirmed_on (only with today or tomorrow's date)
• expected_monthly_revenue_cents
• vat_number
• website_social_media
• business_trading_name
• nace_code
• business_address_line_1
• business_address_line_2
• business_postal_code
• business_city
• business_country
• annual_income_range
• data_terms_signed_at
• branch
• birth_province
• birth_post_code
• socioprofessional_category
• purpose_of_account_opening
• main_income_source
• work_country
• work_province
• self_declared_as_pep
• international_operativity_expectation
• registration_number

Request URL

PATCH /v1/persons/{id}

Request example

{
  "email": "new.email@example.com",
  "address": {
    "line_1": "New Street",
    "line_2": "1",
    "postal_code": "10119",
    "city": "Berlin",
    "country": "DE"
  }
}

• API Reference: Update person

Step 3: Create customer credit record

Create a consumer credit record and link it to the customer's person resource.

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 4: Create customer loan application

Collect loan-specific information and create the application.

POST Create consumer loan application

This endpoint creates the application and assigns it to the person specified in the URL. The payload initiates the credit checks.

Mandatory properties:

• requested_loan_term
• requested_loan_amount
• repayment_day_of_month
• private_insurance_amount
• number_of_dependents
• net_income_amount
• living_situation_amount
• living_situation
• moved_in_last_two_years
• credit_record_id
• loan_purpose
• partner_reference_number

Financed goods properties: For loans financing a purchase, include:

• cash_price
• seller
• financed_good

Request URL

POST /v1/persons/{person_id}/consumer_loan_applications

Scoring & Response

The system automatically scores the application:

• Approved: status becomes offered. Returns a binding offer (amount, term, interest rate, installment).

• Rejected: status becomes rejected.

• API Reference: Create application

GET Retrieve consumer loan application

Track the application lifecycle using this endpoint.

Request URL

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

💡 Webhook: Subscribe to CONSUMER_LOAN_APPLICATION to receive automatic updates whenever the application status changes (e.g., from screening_pending to approved).

• API Reference: Retrieve application

Application status flow

The following diagram illustrates the application status transitions:

POST Generate a subsidized offer (Optional)

Create a subsidized offer with a reduced interest rate by adding the interest_rate in the request body.

Request URL

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

• API Reference: Create subsidized offer

Step 5: Create account snapshot

Create an account snapshot and link it to the application when the status is offered.

PUT Skip account snapshot (Optional)

To skip this step and proceed directly to approved:

Request URL

PUT /v1/persons/{person_id}/consumer_loan_applications/{application_id}/skip_account_snapshot

• API Reference: Skip snapshot

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

Link the snapshot to the application using the account_snapshot_id. This changes the status to account_snapshot_verification and triggers the final credit check.

Request URL

PUT /v1/persons/{person_id}/consumer_loan_applications/{application_id}/account_snapshot

{
  "account_snapshot_id": "0a3f28733f9a4842842aae2804f80eb4snap"
}

💡 Webhook: Subscribe to the ACCOUNT_SNAPSHOT webhook to be notified when the snapshot is successfully created and verified.

• API Reference: Link snapshot

PUT Upload purchase contract (Optional)

If financing a specific asset (e.g., a car), upload the purchase contract.

Request URL

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

• API Reference: Upload contract

Step 6: Send SECCI form and loan contract

You must provide the customer with the Standard European Consumer Credit Information (SECCI) form and the final contract for review.

GET Retrieve SECCI form

Generate the SECCI form as a PDF and share it with the customer before sending the final contract.

Request URL

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

• API Reference: Download SECCI

GET Retrieve final contract

After the customer approves the SECCI form, generate the final contract for e-signing.

Request URL

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

• API Reference: Download contract

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

Trigger the video identification session (IDnow). The agent verifies the customer's identity and mobile number, and collects the Qualified Electronic Signature (QES) on the loan contract, SDD mandate, and terms.

Proceed when the application status is esign_pending.

GET Retrieve the signing ID

When the status is esign_pending, call GET Retrieve consumer loan application to obtain the signing_id.

GET Retrieve e-signing and identification details

Use the signing_id to get IDnow details (reference and URL). Redirect the customer to the returned URL.

Request URL

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

• API Reference: Retrieve signing

💡 Webhook: Subscribe to the IDENTIFICATION webhook. It will send a notification (e.g., status: successful) when the customer completes the video interview.

GET Retrieve signed contracts

After successful identification, retrieve the signed documents.

Request URL

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

GET Download a document

Download specific signed files to share with the customer.

Request URL

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

• API Reference: Download file

GET Retrieve identification details

Verify the identification status is successful.

Request URL

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

• API Reference: Retrieve identification

Step 8: Create the loan

Create the loan to trigger the payout when the application status is loan_creation_pending.

PUT Pay out a customer loan

This endpoint assigns the loan and issues the payout to the recipient IBAN.

Request URL

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

Response

Returns the loan_id. The application status changes to loan_created.

• API Reference: Create loan

GET Retrieve consumer loan information

Retrieve loan details, status, and overdue amounts.

Request URL

GET /v1/loans/{loan_id}

💡 Webhook: Subscribe to the LOAN webhook to track ongoing status changes during the loan lifecycle (e.g., repayments, overdue alerts).

• API Reference: Retrieve loan

Step 9: Loan servicing

Implement endpoints for servicing and maintaining consumer loans.

Loan Servicing Endpoints

Implement these endpoints to manage the active loan lifecycle, including retrieving status, schedules, and history.

Key Endpoints:

• GET Retrieve a loan
• GET Index all loans
• GET Retrieve a loan schedule
• GET Retrieve repayment history
• GET Retrieve credit line mandate

GET Retrieve a loan schedule

Call this endpoint to retrieve the latest repayment schedule for a specific loan. The response includes:

• Loan balance: The remaining amount to be paid.
• Loan installments: A list of past and future scheduled payments.

Request URL

GET /v1/loans/{loan_id}/repayment_schedule

• API Reference: Retrieve loan schedule

GET Retrieve repayment history

Call this endpoint to view the history of all payments made towards the loan. The response includes:

• SEPA Direct Debits (SDD): Automatic monthly installments pulled from the reference account.
• SEPA Credit Transfers (SCT): Manual transfers made by the customer for partial or full early repayment (if applicable).

Request URL

GET /v1/loans/{loan_id}/repayment_history

• API Reference: Retrieve repayment history

Related resources

The following guides and API references are relevant to the Consumer Loans integration:

• Consumer Loans API Reference
• Loan Servicing API Reference
• Video Identification Guide
• SEPA Transfers Overview
• SEPA Direct Debit Transfers

Appendix I: Enums

Consumer loan application status

Document types

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

IDnow status

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

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