Freelancer Overdrafts

This guide explains the integration process for Solaris' Freelancer Overdraft product, including the mandatory information you need to collect from your customer and the necessary endpoints and webhooks you need to integrate into your solution.

Introduction

Product specifications

Freelancer overdrafts are currently only available for customers in Germany with a current bank account with Solaris. For step-by-step instructions on freelancer onboarding for Digital Banking and Cards, check the Freelancer onboarding guide.

Check the overview page for more details on the product specifications.

User journey

Your customers can apply for an overdraft on your frontend by completing the following steps:

  • Provide the mandatory information for overdrafts onboarding.
  • Consent to Solaris' performing an account snapshot and credit checks in relation to the overdraft application.
  • Once the customer passes the credit checks, the application will be approved, and the customer receives a notification and the pre-contractual overdraft agreement and terms and conditions to review.
  • The customer must sign the overdraft's terms and conditions and agreement.
  • Solaris creates the overdraft on the customer's account and the customer can use the overdraft limit right away.

Credit scoring

Solaris uses an automated credit scoring system (Freelancer Overdraft Scorer) to make informed credit decisions on freelancer overdraft 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 checks done throughout the application lifecycle, the scorer estimates the probability of default (PD), determining the customer's rating class, whether an overdraft is offered and the limit amount granted.

Credit risk analysis

The scorer uses the following information in the credit risk analysis:

1. Account snapshot

Solaris collects information about the customer's account data and history from their current account with Solaris. Such information includes account balance, transaction history, bookings, and recurrent repayment amounts.

2. Information from credit agencies

Credit information and score about the customer, collected from external Credit Bureaus (e.g., SCHUFA).

note

Currently, external Credit Bureaus refer to SCHUFA. However, Solaris' scorer interface supports handling any number of external sources.


Webhooks

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

  • OVERDRAFT_APPLICATION: The status of a freelancer overdraft application has changed.
  • OVERDRAFT: The status of a freelancer overdraft has changed.
  • PERSON_CREDIT_RECORD: The status of a freelancer's credit record has changed.

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


Integration flow

The following diagram gives an overview of the integration flow for Freelancer Overdrafts:

Diagram: Freelancer overdraft flow

Integration steps

Important

Overdrafts can only be offered to existing customers who already have a current account.

Integrate Solaris' Freelancer Overdrafts by completing the following steps:

Freelancer overdraft application creation

  1. Collect the required information for the overdraft application from your customers on your frontend.
  2. Collect the contact address from the freelancer if their current address is younger than 2 years and update their person resource by completing Step 1.
  3. Customers consent to performing an account snapshot and credit checks in relation to the overdraft application.
  4. Create a credit record for the freelancer by completing Step 2.
  5. Create a freelancer overdraft application by completing Step 3.
  6. Create an account snapshot and link it to the application by completing Step 4.

Overdraft creation and servicing

If Solaris rejects the overdraft application, notify the customer of the rejection on your frontend.

If Solaris accepts the overdraft application:

  1. Notify the customer of the approval on your frontend.
  2. Send Solaris' special terms and conditions for overdrafts and the pre-contractual overdraft agreement to the customer as a PDF.
  3. Record the customer's consent to the terms and conditions and the overdraft loan agreement as a UTC timestamp.
  4. Create the overdraft on the customer's account by completing Step 5.
  5. Solaris credits the overdraft limit to the customer's account as an external balance.
  6. Check the section Servicing overdrafts for additional information on how to maintain and service overdrafts for your customers.

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


Step 1: Update the customer person resource

As a first step, you must collect the contact_address from the customer and update their person resource. This is important if the customer's address has changed in the past two years to avoid rejection due to address mismatch.

Request example

note

This action will trigger the change request process (unless the property being updated has a value of null).

Copy
Copied
PATCH /v1/persons/{id}
{
    "contact_address": {
        "line_1": "Musterstrasse 10",
        "line_2": null,
        "postal_code": "78550",
        "city": "Musterstadt",
        "country": "DE",
        "state": "BE"
    }
}

Click here to view the full API reference.


Step 2: Create freelancer credit record

In this step, you must create a freelancer 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 freelancers.

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 freelancer

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/freelancers/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 freelancer 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 freelancer overdraft application

In this step, you must pass the mandatory information you collected from the customer in your sign-up flow to Solaris by creating a freelancer overdraft application.

The overdraft application includes all the required information about the customer and links to other mandatory resources, such as credit_record or account_snapshot, which the credit scorer uses to initiate a series of credit checks.

POST Create freelancer overdraft application

This endpoint creates a freelancer overdraft application for the given customer with the person_id specified in the request URL.

Mandatory properties:

Add the following mandatory properties in the request body:

  • credit_record_id: The unique ID of the freelancer credit record created in the previous step.

Request URL

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

Response example

The API call returns an object with a unique id for the freelancer overdraft application, including the application status, set initially to initial_scoring_pending, and the remaining attributes, which will be populated during the application lifecycle.

Copy
Copied
{
  "status": "initial_scoring_pending",
  "rejection_reasons": [
    "null"
  ],
  "person_id": "dc1a6812a14f6cc338cd084208535bcdcper",
  "partner_risk_class": "d",
  "partner_reference_number": "a123456",
  "partner_contact_number": "+491565904345",
  "partner_contact_name": "Peter Mustermann",
  "overdraft_rate": 0,
  "overdraft_id": "string",
  "limit": {
    "value": 0,
    "unit": "cents",
    "currency": "EUR"
  },
  "interest_conditions_enabled": "boolean",
  "interest_accrual_rate": 0,
  "id": "b83z264de98741018419b53648e20ca9coap",
  "decision": "string",
  "credit_record_id": "fbb7d15fa4c54ba0b077592665ef04a4ccrd",
  "created_at": "2021-08-03T18:01:48.000Z",
  "account_snapshot_id": "string"
}

Click here to view the full API reference

GET Retrieve freelancer overdraft application

This endpoint returns the current status and details of an existing freelancer overdraft application. For a list of possible values of the application status and their descriptions, check the Appendix.

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

Request URL

Copy
Copied
GET /v1/persons/{person_id}/overdraft_applications/{overdraft_application_id}

Response example

Copy
Copied
{
  "status": "initial_scoring_pending",
  "rejection_reasons": [
    "null"
  ],
  "person_id": "dc1a6812a14f6cc338cd084208535bcdcper",
  "partner_risk_class": "d",
  "partner_reference_number": "a123456",
  "partner_contact_number": "+491565904345",
  "partner_contact_name": "Peter Mustermann",
  "overdraft_rate": 0,
  "overdraft_id": "string",
  "limit": {
    "value": 0,
    "unit": "cents",
    "currency": "EUR"
  },
  "interest_conditions_enabled": "boolean",
  "interest_accrual_rate": 0,
  "id": "b83z264de98741018419b53648e20ca9coap",
  "decision": "string",
  "credit_record_id": "fbb7d15fa4c54ba0b077592665ef04a4ccrd",
  "created_at": "2021-08-03T18:01:48.000Z",
  "account_snapshot_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 overdraft application.

note

You can use the option to create an account snapshot via Solaris.

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 overdraft application

This endpoint links an account snapshot to an overdraft application. You must include the account_snapshot_id in the payload of this endpoint.

Request URL:

Copy
Copied
PUT /v1/persons/{person_id}/overdraft_applications/{overdraft_application_id}/account_snapshot

Click here to view the full API reference

After linking the account snapshot, the overdraft application status changes to account_snapshot_verification_pending. This is the final step in the data verification process and credit risk analysis. Afterward, Solaris gives the final verdict on the overdraft application, changing the application status to either offered or rejected.


Step 5: Create the overdraft

After Solaris approves the overdraft application, the application status changes to offered. Afterward, you have to do the following steps:

  1. Inform the customer of the approval on your frontend, and show the offered overdraft limit and applicable interest rates.
  2. Collect and record the customer's consent to Solaris' overdrafts terms and conditions and the overdraft loan agreement as a UTC timestamp.
  3. Create the overdraft on the customer's account by calling the following endpoint.

PUT Create the overdraft

This endpoint creates the overdraft on the customer's account. You have to add the customer's account_id in the request body of this endpoint.

Request URL

Copy
Copied
PUT /v1/persons/{person_id}/overdraft_applications/{overdraft_application_id}/overdraft

Example response

The API call returns the overdraft information, including the overdraft id, limit, and overdraft_rate. Afterward, the overdraft application status changes to overdraft_created.

Copy
Copied
  {
    "status": "created",
    "person_id": "dc1a6812a14f6cc338cd084208535bcdcper",
    "overdraft_rate": 9,
    "limit": {
      "value": 3000,
      "unit": "cents",
      "currency": "EUR"
    },
    "interest_conditions_enabled": true,
    "interest_accrual_rate": 3,
    "id": "00556cd181f2409aaa6c2a033cce3a8fcovd",
    "created_at": "2021-08-03T18:01:48.000Z",
    "account_id": "575189c6eb825b10b9d0392fcb3bf61dcacc"
  }

Click here to view the full API reference

GET Retrieve overdraft

This endpoint returns all the details of an existing freelancer overdraft, assigned to the person with the given person_id in the request URL.

Request URL

Copy
Copied
GET /v1/persons/{person_id}/overdrafts/{overdraft_id}

Example response

The API call returns the overdraft object with the unique id and includes the overdraft's details, such as limit and overdraft_rate. The status returned in the response refers to the overdraft's status. For a list of possible values and their descriptions, check the Appendix.

Copy
Copied
  {
    "status": "created",
    "person_id": "dc1a6812a14f6cc338cd084208535bcdcper",
    "overdraft_rate": 9,
    "limit": {
      "value": 1000,
      "unit": "cents",
      "currency": "EUR"
    },
    "interest_conditions_enabled": true,
    "interest_accrual_rate": 3,
    "id": "00556cd181f2409aaa6c2a033cce3a8fcovd",
    "created_at": "2021-08-03T18:01:48.000Z",
    "account_id": "575189c6eb825b10b9d0392fcb3bf61dcacc"
  }

Click here to view the full API reference


Servicing overdrafts

This section includes important information about handling and monitoring active overdrafts.

Overdrafts limits and interest

Overdraft limits cannot be exceeded for any SEPA transfers, direct debits, payments, or withdrawals, except for charged interest fees by Solaris. Any payment exceeding the limit will be rejected.

Overdrafts monitoring

For specific overdraft-related events, you must monitor the account, implement specific event triggers, and provide pre-defined messages to the user. Solaris will provide the message texts.

You have to implement event triggers and send out reminders to customers in the following events:

  • The customer has used 90% of the overdraft limit or only 100€ remaining in the limit.
  • Three days before the interest payment is due to ALL customers with a used overdraft at the end of each quarter.

Overdrafts booking types

Using the overdraft limit reflects on the customer's account statement for interest charges. The following booking types are distinct to overdraft interest charges:

  • InterestOverdraft: The interest accrued in relation to the used portion of the overdraft limit.
  • InterestOverdraftExceeded: The interest accrued in relation to exceeding the overdraft limit (Note that the limit itself cannot be exceeded for regular transactions except for interest charges).

Overdrafts termination

To terminate an overdraft, you must send an overdraft termination request to Solaris either via creating a JIRA ticket or by sending an email to support@solarisbank.de. Solaris will process the request internally and remove the overdraft limit from the customer's account.

attention

Terminating an overdraft CANNOT be reversed. However, a customer can apply for a new overdraft.

Account closure for accounts with an overdraft

In case of Account Closure Requests (ACR) for accounts with an attached overdraft, you must first terminate the overdraft before initiating the ACR process.


What's next?

Congratulations! You've successfully integrated Solaris' Freelancer Overdraft 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

Freelancer overdraft application status

These are the possible values for the field status in the freelancer overdraft application resource.

Status Description
initial_scoring_pending Solaris successfully received the overdraft application and is assessing and scoring the application. This is the first step of the credit scoring process, which involves checking and evaluating the customer's overdraft application and credit record.
account_snapshot_pending The customer passed the first step of credit scoring, and the second step can start. To kick off the following steps, you have to attach the customer's account snapshot to the overdraft application.
account_snapshot_verification_pending The account snapshot is successfully linked to the overdraft application and will be assessed by Solaris' credit scoring system.
offered Credit checks were successful, and Solaris approved the overdraft application.
rejected Credit checks were unsuccessful, and Solaris rejected the overdraft application. Rejection could be due to failed initial credit scoring or failed account snapshot verification.
expired Either the credit record or the account snapshot is expired. New ones must be created and linked to the overdraft application to resume the process.
deleted The overdraft application was deleted.
overdraft_created The overdraft is created in the customer's account.

Freelancer overdraft status

These are the possible values for the field status, which indicates the status of an overdraft that is already offered.

Status Description
created The overdraft is created.
interest_conditions_set Which interest conditions are applied to the overdraft. It indicates whether interest_accrual_rate or overdraft_rate is applied on the overdraft.
limit_set The overdraft limit is set and available for use in the customer's account.