# Consumer loans This guide explains the integration process of Solaris' Loan product for retail customers (Consumers) as a standalone solution, including the mandatory information you must collect from your customers and the necessary endpoints and webhooks you must integrate into your solution. ## Introduction ### Product specifications Solaris' Consumer Loans product enables you to offer loans to your retail customers in a simple and efficient workflow. With just a few API calls and an automated credit scoring system, you can create loan applications, identify your customers, issue loan payouts, and service consumer loans. Solaris' Loans are versatile and can be tailor-made to your use case. Our standard offering includes loan amounts ranging from EUR 1,000 to 50,000 and loan terms from 12-84 months. You can choose between a standard loan or a loan tied to financing the purchase of goods. Important Consumer loans are currently only offered to customers in **Germany** with at least one German bank account. ### Credit scoring Solaris uses an automated retail credit scoring system to make informed credit decisions on consumer loan applications. The scorer collects and analyzes different information, such as the customer's financial information, credit data, transaction history, and outstanding loans to assess their creditworthiness and determine their risk level and credit eligibility. Based on different credit checks done throughout the application lifecycle, the scorer estimates the probability of default (PD) and then determines whether to offer a loan. It also determines the amount, term, and interest rate to be offered. **How does the scorer interact with the consumer loan service?** The consumer loan service handles consumer loan requests and collects the required information about the applicants, such as self-declared financial information, credit records, and account snapshots. Throughout the lifecycle of a consumer loan application, the scorer provides different responses based on the information provided during each stage of the application. The scorer performs different credit checks throughout the application lifecycle, such as: - **Anonymous offer**: In this stage, the scorer evaluates the self-declared information the applicant provided when requesting an anonymous non-binding loan offer. The scorer gives an immediate decision to the customer. This check only happens if you've implemented the anonymous offer endpoint in your solution. - **Binding offer**: The scorer decides whether to make a binding offer by analyzing the consumer loan application and the credit record obtained from external credit bureaus, such as SCHUFA. - **Verification**: The scorer uses the account snapshot to verify the financial information provided in the consumer loan application. This is the final check, after which the scorer provides the final decision. This step can be skipped based on your configurations. ## 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](/guides/get-started/technical-setup). **2. Legal and compliance screens:** Build the necessary legal and compliance screens in your sign-up flow to collect your customers' consent to the necessary legal and compliance requirements. The [Legal and compliance screens guide](/guides/get-started/onboarding-requirements/1-legal-compliance-screens) 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](/guides/get-started/onboarding-requirements/1-legal-compliance-screens/#solaris-terms--conditions) 2. [Customer information](/guides/get-started/onboarding-requirements/1-legal-compliance-screens/#customer-information) 3. [Economic interest](/guides/get-started/onboarding-requirements/1-legal-compliance-screens/#economic-interest) Record the customer's consent on each screen as a UTC timestamp (e.g., `2019-01-01T00:00:00Z`). Afterward, you must pass each timestamp in its respective field to Solaris. - Collect the customer's consent to Solaris's Terms and Conditions and store the timestamp in the `terms_conditions_signed_at` field. - Collect the customer's consent to data processing and store the timestamp in the `data_terms_signed_at` field. - Collect the customer's economic interest declaration and store the timestamp in the `own_economic_interest_signed_at` field. :::note The mentioned fields are part of the person resource in which all the customer data points are stored. ::: ## Integration overview The following sequence diagram gives an overview of the integration flow for the Consumer Loans solution: ![Diagram: Consumer Loans flow](/assets/b2c-loan-flow.e33566ade8ea536e96e194fe6fb3618d370e51ca09ff02a59de073aa8482791d.da581abd.svg) Important - This guide includes the integration process for Consumer Loans as a **standalone** solution, i.e., the loan will be credited to an external account. - For existing customers who already have a current account with Solaris and wish to apply for a loan, skip [Step 2](#step-2-collect-customer-data-and-create-person-resource). Integrate Solaris' Consumer Loans by completing the following steps: | Stage | Step | Description | | --- | --- | --- | | Customer registration | [Step 1 - Optional](#step-1-generate-an-anonymous-offer-for-a-loan-optional) | Generate an anonymous loan offer for the customer. | | Customer registration | [Step 2](#step-2-collect-customer-data-and-create-person-resource) | 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. | | Loan application | [Step 3](#step-3-create-customer-credit-record) | Create a credit record for the customer. | | Loan application | [Step 4](#step-4-create-customer-loan-application) | Create a loan application for the customer and include all mandatory data points required for the scorer. | | Loan application | [Step 5](#step-5-create-account-snapshot) | Create an account snapshot for the customer and link it to the loan application. | | Customer identification & contract signing | [Step 6](#step-6-send-secci-form-and-loan-contract) | Send the customer the SECCI form and the loan final contract. | | Customer identification & contract signing | [Step 7](#step-7-complete-the-customer-identification-and-e-signing-process) | Trigger the KYC and e-signing flow for the customer, and redirect the customer to complete the identification process with IDnow and sign the relevant contracts. Ensure that the customer is successfully identified and passes the risk screening before proceeding with the following steps. | | Loan creation & servicing | [Step 8](#step-8-create-the-loan) | Create the loan for the customer to trigger the loan payout to the customer's desired account. | | Loan creation & servicing | [Step 9](#step-9-loan-servicing) | Implement the endpoints related to loan servicing and maintenance in your solution. | You can find detailed descriptions of these steps and their related endpoints in the following sections. ### Webhooks Solaris recommends subscribing to the following webhook events to better automate your processes. For detailed instructions on implementing Solaris webhooks, check the [webhooks documentation](/api-reference/webhooks/). - [ACCOUNT_SNAPSHOT](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/account_snapshot/post) - [CONSUMER_LOAN_APPLICATION](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/consumer_loan_application/post) - [IDENTIFICATION](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/identification/post) - [PERSON_CHANGED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_changed/post) - [PERSON_DELETED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_deleted/post) - [PERSON_MOBILE_NUMBER_CREATED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_mobile_number_created/post) - [PERSON_MOBILE_NUMBER_DELETED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_mobile_number_deleted/post) - [LOAN](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/loan/post) ### Mandatory features You must integrate all the mandatory features for B2C Loans highlighted in the [Onboarding requirements guide](/guides/get-started/onboarding-requirements/6-mandatory-features/#lending) before going live with your solution. ## Step 1: Generate an anonymous offer for a loan (Optional) In this step, you can give your customers the opportunity to receive a **non-binding** anonymous loan offer before starting the loan application process or providing any personal data. This is an **optional** step that you can implement in your sign-up flow to give your customers the flexibility to check their eligibility for a loan before starting the process. **How does it work?** The customer enters their desired loan amount and duration along with their self-declared financial information in your frontend. Based on this information, Solaris' automated credit scoring system evaluates the customer's credit risk and eligibility and immediately provides either an initial approval or a rejection. In case of approval, the customer receives a **non-binding** loan offer, including the loan amount and term, interest rate, and monthly installment amount. This offer is only based on the self-declared information and the customer must start the application process to receive the final credit approval and binding offer. In case of rejection at this stage, the customer receives either an adjusted loan offer (e.g., a lower loan amount or longer loan term) or a rejection. ### POST Generate anonymous loan offer This endpoint generates a non-binding anonymous loan offer for a customer based on their self-declared and unverified financial information. You must add the following mandatory fields in the request body of this endpoint: - `requested_loan_term` - `requested_loan_amount` - `requested_emi` - `private_insurance_amount` - `number_of_dependents` - `net_income_amount` - `living_situation_amount` - `living_situation` - `existing_credit_repayment_excluding_mortgage` **Request URL** ```shell POST /v1/anonymous_consumer_loan_offers ``` **Response example** The API call returns a non-binding loan offer, including the loan term, amount, monthly installment, and interest rate, as well as the loan decision, which can be either `OFFERED` or `REJECTED`. The loan decision returned by calling this endpoint is NOT final and is only based on the self-declared information. Additionally, the loan offer is NOT binding and the customer must initiate the loan application process to receive the final offer and approval. [Click here to view the full API reference.](/api-reference/lending/loans/#operation/ConsumerLoanWeb.V1.AnonymousOffers.CreateOperation) After the customer decides to apply for a loan, you must then collect the mandatory information from the customer on your frontend by continuing with the following steps. ## Step 2: Collect customer data and create person resource In this step, you have to collect the mandatory data points from the customer in your sign-up flow, including all the timestamps of the customer's consent to the [legal and compliance screens](#system-prerequisites). Afterward, pass all the data points to Solaris by creating a [person resource](/guides/get-started/onboarding-requirements/2-data-collection/#customer-data-resource-types) 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](/api-reference/onboarding/persons/#tag/Persons): - [POST Create person](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons/post) - [GET Retrieve a person](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons~1%7Bid%7D/get) - [PATCH Update person](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons~1%7Bid%7D/patch) **Related webhook events** - [PERSON_CHANGED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_changed/post) - [PERSON_DELETED](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_deleted/post) :::info Important points about data collection - Please consider the special requirements for data collection highlighted in the [onboarding requirements guide](/guides/get-started/onboarding-requirements/2-data-collection/#important-considerations-for-data-collection). - You must submit the information exactly as it appears in official documents. - When testing the process on Sandbox, please ensure that each person you create has unique values for `first_name`, `last_name`, `birth_city`, and `birth_date`. If you create over 1000 identical person resources, the API will return a `400` error. - Don't use any personal data when testing this endpoint on Sandbox. ::: #### POST Create person Call this endpoint to create a person resource for your customer, and add the following mandatory data points in the request body: **Mandatory data points for retail customers in Germany** - `salutation` - `first_name` - `last_name` - `address` - `line_1` - `line_2` - `postal_code` - `city` - `country` - `mobile_number` - `birth_date` - `birth_city` - `birth_country` - `nationality` - `employment_status` - `terms_conditions_signed_at` - `data_terms_signed_at` - `own_economic_interest_signed_at` - `tax_information` - `marital_status` **Request URL** ```shell POST /v1/persons ``` [Click here to view the full API reference.](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons/post) #### 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` :::attention - Fields not mentioned in this list can only be updated via Customer Support. - **Only for B2C customer**: If a customer changes their `employment_status` to `FREELANCER` or `SELF_EMPLOYED`, please note that you must apply one of the following options to the same request to avoid getting an error: 1. Collect the `nace_code` from the customer, or 2. Set the fields `industry` and `industry_key` to `null`. - Solaris recommends collecting the `nace_code` from the customer for the sake of data quality. ::: **Request URL** ```shell PATCH /v1/persons/{id} ``` [Click here to view the full API reference](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons~1%7Bid%7D/patch) ## Step 3: 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. :::attention 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. - [Credit record resource API reference](/api-reference/lending/credit-record/#tag/Person-credit-record) To create a credit record for your customer, you can use one of the following endpoints depending on your customer type. You can create a credit record in two ways: **1. Via Solaris:** To create a credit record via Solaris, set the `source` field to `solarisBank` in the request body and Solaris will pull the customer's record directly from SCHUFA. **2. Manual upload:** In this case, you will collect the credit record manually through SCHUFA and/or other third-party service providers and upload the file to Solaris. Set the `source` field to `partner` and include the file content in the `file` field (Base64-encoded). #### POST Create a credit record for a retail customer **Request URL** ```shell POST /v1/persons/{person_id}/credit_records ``` [Click here to view the full API reference](/api-reference/lending/credit-record/#operation/PersonCreditRecordWeb.V1.CreditRecords.CreateOperation) #### POST Create a credit record for a freelancer **Request URL** ```shell POST /v1/freelancers/persons/{person_id}/credit_records ``` [Click here to view the full API reference](/api-reference/lending/credit-record/#operation/PersonCreditRecordWeb.V1.CreditRecords.CreateFreelancerOperation) #### GET Retrieve a 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. **Request URL** ```shell GET /v1/persons/{person_id}/credit_records/{credit_record_id} ``` [Click here to view the full API reference](/api-reference/lending/credit-record/#operation/PersonCreditRecordWeb.V1.CreditRecords.ShowOperation) ## Step 4: Create customer loan application In this step, you need to collect additional information from the customer related to the consumer loan application, and pass them to Solaris using the following endpoint: ### POST Create consumer loan application This endpoint creates a consumer loan application and assigns it to the person with the `person_id` specified in the request URL. The consumer loan application includes all the required information about the customer, such as their financial information, credit record, and loan information, which Solaris' credit scorer uses to initiate a series of credit checks. **Mandatory properties:** Add the following mandatory properties in the request body: - `requested_loan_term` - `requested_loan_amount` - `requested_emi` - `repayment_day_of_month` - `private_insurance_amount` - `number_of_dependents` - `net_income_amount` - `living_situation_amount` - `living_situation` - `existing_credit_repayment_excluding_mortgage` - `moved_in_last_two_years` - `credit_record_id` - `loan_purpose` - `partner_reference_number` For loans related to the purchasing of goods, the following fields are also mandatory: - `cash_price` - `seller` - `financed_good` **Request URL** ```shell POST /v1/persons/{person_id}/consumer_loan_applications ``` The API call returns an object with a unique `id` (i.e., the `application_id`), including the application `status` and the remaining attributes, which will be populated during the application lifecycle. **Scoring** This API call automatically triggers Solaris' automated retail credit scoring system, which scores the application and provides its decision on the loan application. **Approved application** If Solaris' scorer approves the loan application, the application `status` changes to `offered` and the `loan_decision` value will change to `OFFERED`. The response body will include the binding offer for the loan, including the loan amount, term, interest rate and monthly installment. **Rejected application** In case of rejection, the application `status` changes to `rejected` and `loan_decision` will be set to `REJECTED`. [Click here to view the full API reference.](/api-reference/lending/loans/#operation/ConsumerLoanWeb.V1.Applications.CreateOperation) ### GET Retrieve consumer loan application Call this endpoint to retrieve a customer's consumer loan application and track the application lifecycle through the `status` field. Additionally, subscribe to the webhook event `CONSUMER_LOAN_APPLICATION` to receive status updates about the application. Check the [appendix](#consumer-loan-application-status) for a list of possible values and descriptions for the `status` field. Additionally, check the application status flow [here](#application-status-flow). **Request URL** ```shell GET /v1/persons/{person_id}/consumer_loan_applications/{application_id} ``` [Click here to view the full API reference.](/api-reference/lending/loans/#operation/ConsumerLoanWeb.V1.Applications.ShowOperation) ### Application status flow The following diagram describes the status flow of a consumer loan application: ![Diagram: Consumer loan application flow](/assets/b2c-loan-application-status.265e4b8c105a8b323bdc5ff73d7caa1aaa495684494ba65c4a1230ff6a8de572.da581abd.svg) ### POST Generate a subsidized offer for a consumer loan application (Optional) This endpoint creates a subsidized loan offer with a reduced interest rate. You can call this endpoint and add the required interest rate in the request body to receive the new offer. You have to pay Solaris the difference between the initial offered rate and the requested reduced one. **Request URL** ```shell POST /v1/persons/{person_id}/consumer_loan_applications/{consumer_loan_application_id}/offers/{offer_id}/subsidize ``` [Click here to view the full API reference.](/api-reference/lending/loans/#operation/ConsumerLoanWeb.V1.Applications.CreateSubsidizedOfferOperation) ## Step 5: Create account snapshot In this step, you must create an account snapshot for the customer and link it to their consumer loan application. Complete this step when the application `status` changes to `offered`. ### PUT Skip the account snapshot process for a consumer loan application (Optional) Call this endpoint if you want to skip this step for a customer. This endpoint will override this requirement and the application status will proceed directly to `approved`. **Request URL** ```shell PUT /v1/persons/{person_id}/consumer_loan_applications/{application_id}/skip_account_snapshot ``` [Click here to view the full API reference.](/api-reference/lending/loans/#operation/ConsumerLoanWeb.V1.Applications.SkipAccountSnapshotOperation) ### What is an account snapshot? The account snapshot contains a breakdown of the customer's account information, such as balance, transactions, bookings, and recurrent repayment amounts over a certain period of time. Creating an account snapshot is usually required in lending products integrations as it's used for credit scoring to verify the customer's financial data. Integrate the following endpoints to create account snapshots for your customers. ### API reference Visit the following link to find all the endpoints related to the account snapshot resource, including related properties and examples. - [Account snapshot resource API reference](/api-reference/lending/account-snapshot/#tag/Account-snapshots) #### 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](https://docs.fintecsystems.com/). 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** ```json 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`. ```json { "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](https://docs.finx.finleap.cloud/#section/Native-Mobile-App-Integration). 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** ```json 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. ```json { "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** ```json 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`. ```json { "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** ```json { "source": "SOLARISBANK", "account_id": "adc123a45d6d7cf8fbfeed537ba919d5cacc" } ``` **Response example** The API call returns a resource with a unique ID, the `account_snapshot_id`. ```json POST /v1/persons/{person_id}/account_snapshots { "wizard_session_key": null, "location": null, "id": "0a3f28733f9a4842842aae2804f80eb4snap", "account_id": "adc123a45d6d7cf8fbfeed537ba919d5cacc" } ``` [Click here to view the full API reference](/api-reference/lending/account-snapshot/#operation/AccountSnapshotWeb.V1.AccountSnapshots.CreateOperation) #### 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** ```shell GET /v1/persons/{person_id}/account_snapshots/{account_snapshot_id} ``` [Click here to view the full API reference](/api-reference/lending/account-snapshot/#operation/AccountSnapshotWeb.V1.AccountSnapshots.ShowOperation) #### PUT Link customer account snapshot to consumer loan application After creating an account snapshot, use this endpoint to link the customer's account snapshot to their existing credit line application. You must add the `account_snapshot_id` in the request body. Once linked, the application status changes to `account_snapshot_verification`. Additionally, this action prompts the credit scoring system to perform the final verification and verify the self-declared financial information based on the customer's income, expenses, and recurring credit repayments. After successful verification, the application status changes to `approved` or `rejected`. **Request URL** ```shell // PUT /v1/persons/{person_id}/consumer_loan_applications/{application_id}/account_snapshot { "account_snapshot_id": "0a3f28733f9a4842842aae2804f80eb4snap" } ``` [Click here to view the full API reference.](/api-reference/lending/loans/#operation/ConsumerLoanWeb.V1.Applications.LinkAccountSnapshotOperation) ### PUT Upload the purchase contract related to the financed good (Optional) If the loan will be used to finance the purchase of a specific asset, e.g., a car, upload the relevant asset purchase contract from the merchant and attach it to the loan application using the following endpoint. **Request URL** ```shell PUT /v1/persons/{person_id}/consumer_loan_applications/{application_id}/upload_purchase_contract ``` [Click here to view the full API reference.](/api-reference/lending/loans/#operation/ConsumerLoanWeb.V1.Applications.UploadPurchaseContractOperation) ## Step 6: Send SECCI form and loan contract Before prompting the customer to sign the final contract of the loan, you must send the customer the Standard European Consumer Credit Information (SECCI) form. The SECCI form is a standardized credit form that includes the information related to a credit offer, such as creditor details, type of credit, amount, duration, interest rates, credit costs, etc. In compliance with regulatory requirements, you must first send the customer the SECCI form to review and approve. Afterward, you can send them the final contract which they have to sign during the identification and e-signing process. Implement the following endpoints to generate the SECCI form and final contract of a loan. ### GET Retrieve the SECCI form of a loan Call this endpoint to generate the SECCI form of the loan offer as a PDF. You must share this form to the customer before sending the final contract either via email or direct download through your app. **Request URL** ```shell GET /v1/persons/{person_id}/consumer_loan_applications/{application_id}/offers/{offer_id}/pre_contract ``` [Click here to view the full API reference.](/api-reference/lending/loans/#operation/ConsumerLoanWeb.V1.Applications.DownloadOfferPreContractOperation) ### GET Retrieve final contract After the customer reviews and approves the loan's SECCI form, call this endpoint to generate the final contract, which the customer must sign electronically during the identification process. It's recommended to share the final contract with the customer via email or direct download prior to the identification process. **Request URL** ```shell GET /v1/persons/{person_id}/consumer_loan_applications/{application_id}/offers/{offer_id}/contract ``` [Click here to view the full API reference.](/api-reference/lending/loans/#operation/ConsumerLoanWeb.V1.Applications.DownloadOfferContractOperation) The customer must also sign an SDD mandate, which authorizes Solaris to debit the customer's account for the monthly installments. For more information about SDD mandates, check the [SEPA DIRECT DEBIT GUIDE](/guides/digital-banking/sepa-transfers/sepa-direct-debit-transfer). ## Step 7: Complete the customer identification and e-signing process In the step, you must prompt the customer to complete the identification process, in which the customer will be identified in a video identification session through our provider IDnow. During this session, an identification agent will verify the customer's data against their identification documents, verify their mobile number, and collect the customer's qualified electronic signature (QES) on the loan contract, SDD mandate, and terms and conditions. Call the following endpoints once the `status` of the consumer loan application changes to `esign_pending`. This guide explains the integration process with video identification as the identification method. For an overview of other available KYC methods, check the [customer KYC products overview](/guides/kyc/) page and consult with your Partner Manager. ### GET Retrieve the signing ID When the application `status` changes to `esign_pending`, it means that the identification and e-signing process has been triggered for the customer. You must call the [GET Retrieve consumer loan application method](#get-retrieve-consumer-loan-application) to get the `signing_id`, which you'll need to retrieve the identification details. ### GET Retrieve e-signing and identification details Once you obtain the `signing_id` from the previous endpoint, call the following method to get the video identification details, such as the IDnow reference and URL. **Request URL** ```shell GET /v1/persons/{person_id}/signings/{signing_id} ``` **Response example** The API call returns the identification details, such as the IDnow `reference` and `url`, to which you must redirect your customer to complete the identification process and the documents your customer must e-sign. The payload also includes the IDnow `status`. ```json { "id": "97b07d67783856a08312f38bf7b7ef2ecidt", "reference": "TST-NGGWH", "url":"https://go.test.idnow.de/solarisbankesignsandbox/identifications/:id", "status": "pending", "completed_at": null, "method": "idnow", "proof_of_address_type": null, "proof_of_address_issued_at": null, "address": null, "documents": [] } ``` [Click here to view the full API reference.](/api-reference/identity/identifications/#tag/Person-signings/paths/~1v1~1persons~1%7Bperson_id%7D~1signings~1%7Bsigning_id%7D/get) - For a list of possible values of the `status` of IDnow process and their descriptions, check the [appendix](#idnow-status). - Additionally, subscribe to the `IDENTIFICATION` webhook event to get IDnow status updates. - Check the [video identification guide](/guides/kyc/videoident/) for more endpoints related to KYC with IDnow. ### GET Retrieve the signed contracts After successful identification and e-signing, call the following endpoint to retrieve the signed contracts. **Request URL** ```shell 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. 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). ```json { "id": "56564cea82e8fdb75765c4a7c92693d1csig", "reference": "TST-TXTSH", "url": "https://go.test.idnow.de/solarisbankesignsandbox/identifications/24f3324d4ad0c023f6623050e750726ecidt/webcam", "state": "finished", "status": "finished", "completed_at": "2020-03-12T15:09:51.000Z", "method": "idnow", "identification_id": "24f3324d4ad0c023f6623050e750726ecidt", "documents": [ { "id": "2b184a18bf7f2f945dfaac55c5ead1b1cdoc", "name": "24f3324d4ad0c023f6623050e750726ecidt_ldoc_signed.pdf", "content_type": "application/pdf", "document_type": "SIGNED_CONTRACT", "size": 116654, "customer_accessible": false, "created_at": "2020-03-12T15:10:15.000Z" }, { "id": "ddffb4706e51ea2f9862ded706760a60cdoc", "name": "24f3324d4ad0c023f6623050e750726ecidt_cdoc_signed.pdf", "content_type": "application/pdf", "document_type": "SIGNED_CONTRACT", "size": 216502, "customer_accessible": false, "created_at": "2020-03-12T15:10:16.000Z" }, { "id": "97ad2cc84dcc665c471675cb671b087ecdoc", "name": "24f3324d4ad0c023f6623050e750726ecidt.xml", "content_type": "application/xml", "document_type": "OTHER", "size": 2829, "customer_accessible": false, "created_at": "2020-03-12T15:10:16.000Z" }, { "id": "681361f0f979393470c29e26f8d2faefcdoc", "name": "24f3324d4ad0c023f6623050e750726ecidt.xml.sig", "content_type": "application/pgp-signature", "document_type": "SIGNATURE", "size": 256, "customer_accessible": false, "created_at": "2020-03-12T15:10:16.000Z" }, { "id": "137a53b807f1c2328c623c35711b32f3cdoc", "name": "24f3324d4ad0c023f6623050e750726ecidt.xml", "content_type": "application/xml", "document_type": "OTHER", "size": 2703, "customer_accessible": false, "created_at": "2020-03-12T15:10:17.000Z" }, { "id": "6b7ba109120ad87ff88c293225463cd5cdoc", "name": "24f3324d4ad0c023f6623050e750726ecidt.xml.sig", "content_type": "application/pgp-signature", "document_type": "SIGNATURE", "size": 256, "customer_accessible": false, "created_at": "2020-03-12T15:10:17.000Z" } ] } ``` ### GET Download a document This endpoint downloads the file of the document with the `id` specified in the request URL. Call this endpoint to download the relevant signed documents to share them with the customer. **Request URL** ```shell GET /v1/persons/{person_id}/documents/{id}/file ``` [Click here to view the full API reference](/api-reference/onboarding/persons/#tag/Person-documents/paths/~1v1~1persons~1%7Bperson_id%7D~1documents~1%7Bid%7D~1file/get) ### 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** ```shell GET /v1/persons/{person_id}/identifications/{id} ``` [Click here to view the full API reference.](/api-reference/identity/identifications/#tag/Person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D/get) ## Step 8: Create the loan After successful customer identification, screening and credit risk checks, you can create the loan for the customer. Call the following endpoint when the application `status` reaches `loan_creation_pending`. ### PUT Pay out a customer loan This endpoint pays out the loan to the customer's specified IBAN and assigns the loan to the customer's with the `person_id` and `application_id` specified in the request URL. **Request URL** ```shell PUT v1/persons/{person_id}/consumer_loan_applications/{application_id}/consumer_loan ``` **Response example** The API call creates a loan resource and returns an `id` (i.e., the `loan_id`). The application `status` should change to `loan_created` after calling this endpoint. ```json { "id": "6c8b5faf3c2d4a5682c5c80ef7382387cloa" } ``` [Click here to view the full API reference.](/api-reference/lending/loans/#operation/ConsumerLoanWeb.V1.Applications.CreateLoanOperation) ### GET Retrieve consumer loan information This endpoint returns the information related to a customer's loan, such as the loan `status`, account details, payouts, overdue amounts, interest rates, etc. - Additionally, subscribe to the `LOAN` webhook event to receive updates about the loan status. **Request URL** ```shell GET /v1/loans/{loan_id} ``` [Click here to view the full API reference.](/api-reference/lending/loans/#operation/LoanEngineWeb.V1.Loans.ShowOperation) ## Step 9: Loan servicing This step includes the different endpoints you need to integrate in your solution for servicing and maintaining consumer loans for your customers. ### API reference Visit the following link to find all the endpoints related to servicing and maintaining loans, including related properties and examples. - [Loan Servicing API Reference documentation](/api-reference/lending/loans/#tag/Loan-servicing): - [GET Retrieve a loan](/api-reference/lending/loans/#operation/LoanEngineWeb.V1.Loans.ShowOperation) - [GET Index all loans](/api-reference/lending/loans/#operation/LoanEngineWeb.V1.Loans.IndexOperation) - [GET Retrieve a loan schedule](/api-reference/lending/loans/#operation/LoanEngineWeb.V1.Loans.RepaymentSchedule.ShowOperation) - [GET Retrieve the history of repayments of a loan](/api-reference/lending/loans/#operation/LoanEngineWeb.V1.Loans.ShowRepaymentHistoryOperation) - [GET Retrieve a credit line mandate](/api-reference/lending/loans/#operation/LoanEngineWeb.V1.Mandates.ShowCreditLineMandateOperation) #### GET Retrieve a loan schedule This endpoint retrieves the latest repayment schedule of the loan specified in the request URL. The call will return information about two components: - Loan balance - Loan installments For detail descriptions about each field, check the API reference. **Request URL** ```shell GET /v1/loans/{loan_id}/repayment_schedule ``` [Click here to view the full API reference.](/api-reference/lending/loans/#operation/LoanEngineWeb.V1.Loans.RepaymentSchedule.ShowOperation) #### GET Retrieve the repayment history of a loan This endpoint retrieves the repayment history of the loan specified in the request URL. The call will return information about two components: - All SEPA Direct Debits (SDD) that were pulled from the customer's reference account tied to the loan. - All SEPA Credit Transfers (SCT) for any partial or full early repayments the customer have made (If applicable). **Request URL** ```shell GET /v1/loans/{loan_id}/repayment_history ``` [Click here to view the full API reference.](/api-reference/lending/loans/#operation/LoanEngineWeb.V1.Loans.ShowRepaymentHistoryOperation) ## What's next? Congratulations! You've successfully integrated Solaris' Consumer Loans solution. Check the following appendices section for additional information on enums and testing data. For an overview of Solaris' lending products, check the lending products [overview](/guides/lending/) page. ### Useful resources Check the following links for additional related guides and API reference documentation: - [Consumer Loans API Reference documentation](/api-reference/lending/loans/#tag/Consumer-Loan) - [Loan Servicing API Reference documentation](/api-reference/lending/loans/#tag/Loan-servicing) - [Person Signings API Reference Documentation](/api-reference/identity/identifications/#tag/Person-signings) - [Video Identification](/guides/kyc/videoident) - [SEPA Transfers Overview](/guides/digital-banking/sepa-transfers) - [SEPA Direct Debit Transfers](/guides/digital-banking/sepa-transfers/sepa-direct-debit-transfer) ## Appendix I: Enums ### Consumer loan application status | Status | Description | | --- | --- | | `offered` | The application has passed the initial scoring step. | | `account_snapshot_verification` | You must create an account snapshot for the customer and attach it to the application to trigger the credit scorer's final verification step. | | `approved` | The application has been approved. | | `esign_pending` | The identification and e-signing process has been triggered for the customer. The signing ID should be available when you call the [GET Retrieve consumer loan application](#get-retrieve-consumer-loan-application) method. | | `screening_pending` | The customer's application is undergoing internal risk screening. | | `esign_failed` | The identification and e-signing process has failed. You need to trigger a new identification for the customer. | | `loan_creation_pending` | The customer identification, e-signing and screening have been completed successfully. A loan can be created and paid out to the customer. | | `loan_created` | A loan has been created and paid out to the customer. | | `rejected` | The application has been rejected. | | `deleted` | The application has been deleted. | | `expired` | The application has expired. An application becomes expired if either the linked credit record or account snapshot have exceeded their validity period. Call the relevant GET methods to check the status of a credit record or an account snapshot and create new ones and link them to the application. | ### Document types The following table includes the possible values for the field `document_type` and their descriptions. | Enum | Description | | --- | --- | | `ANNUAL_FINANCIAL_STATEMENT` | A business or a company's annual financial statement. | | `KYC_REPORT` | The KYC report generate after a successful customer identification. | | `ID_DOCUMENT` | An person's identification document, such as passport or ID. | | `SIGNATURE` | A signature example. | | `PICTURE` | A picture or a scanned document of any other type. | | `QES_DOCUMENT` | A document related to a Qualified Electronic Signature (QES). | | `SIGNED_CONTRACT` | A signed contract of any kind. | | `SIGNED_QES_DOCUMENT` | A document signed by a Qualified Electronic Signature (QES). | | `REGISTER_CHECK` | A register check. | | `REGISTER_EXTRACT` | A business or a company's commercial register excerpt or a similar document. | | `FOUNDATION_DOCUMENT` | The foundation document of a company or business. | | `SCHUFA_COMPACT_REPORT` | A compact SCHUFA report. | | `SCHUFA_GWG_REPORT` | A GWG SCHUFA report. | | `SCHUFA_FULL_REPORT` | A full SCHUFA report about a person. | | `SCHUFA_SHORT_REPORT` | A short SCHUFA report about a person. | | `CREDIT_AGENCY_REPORT` | A report issued by a credit agency. | | `SHARE_HOLDERS_AGREEMENT` | A business or a company's shareholders agreement. | | `SHAREHOLDERS_LIST` | A business or a company's shareholders list. | | `TRADING_LICENSE` | A business or a company's trading license. | | `TRANSPARENCY_REGISTER_EXTRACT` | An extract of a transparency register. | | `INVOICE` | An invoice of any kind. | | `OTHER` | Any other type of document. | | `VIDEO` | A video of any kind. | | `VAT_CERTIFICATE` | VAT registration certificate | ### Idnow status The following table includes the possible values for the field `status` for the video identification process carried out by IDnow and the related description of each status. | Status | Description | | --- | --- | | `created` | The identification resource has been created for the customer. | | `pending` | The identification process has been triggered and the video identification URL and reference are generated. You must redirect the customer to the URL to complete the identification process with IDnow. | | `pending_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 whenever the identification has a `canceled` or `aborted` status. No reason can be disclosed for the final `failed` status.