# Freelancer Overdrafts

This guide explains how to integrate Solaris' Overdraft product for freelancers into your solution.

## Introduction

### Product specifications

Freelancer overdrafts are currently only available for **customers with a current bank account with Solaris**. For more information about overdrafts and how they work, check the [Overview page](/guides/lending/overdrafts).

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

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

## System prerequisites

Before integrating Solaris' Consumer overdrafts for your retail customers, the customers must have been onboarded and have a checking bank account with Solaris. For step-by-step instructions on person onboarding for Digital Banking and Cards, check the [Person onboarding guide](/guides/get-started/digital-banking/onboard-person).

## Integration overview

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

Diagram: Freelancer overdraft flow
Integrate Solaris' Freelancer Overdrafts by completing the following steps:

| Stage | Step | Description |
|  --- | --- | --- |
| Information update | [Step 1](#step-1-update-the-customer-person-resource) | Collect the contact address from the freelancer if their current address is younger than 2 years and update their `person` resource. |
| Credit record | [Step 2](#step-2-create-freelancer-credit-record) | Collect the customer's consent to performing credit checks and create a credit record for the customer. |
| Overdraft application | [Step 3](#step-3-create-freelancer-overdraft-application) | Collect the required information from your customers on your frontend and create an overdraft application. |
| Account snapshot | [Step 4](#step-4-create-account-snapshot) | Create an account snapshot and link it to the application. |
| Overdraft documents | [Step 5](#step-5-create-the-overdraft) | If the application is approved and the status changes to `offered`, create the overdraft on the customer's account. Afterward, Solaris credits the overdraft limit to the customer's account as an external balance. |
| Overdraft servicing | [Step 6](#step-6-servicing-overdrafts) | Integrate all endpoints related to overdrafts servicing. |


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

* [OVERDRAFT_APPLICATION](/api-reference/onboarding/webhooks/webhook-events/paths/overdraft_application/post)
* [OVERDRAFT](/api-reference/onboarding/webhooks/webhook-events/paths/overdraft/post)
* [FREELANCER_OVERDRAFT_INTEREST_RATE_CHANGE](/api-reference/onboarding/webhooks/webhook-events/paths/freelancer_overdraft_interest_rate_change/post)


## 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**

This action will trigger the [change request](/guides/authentication/strong-customer-authentication#change-request) process (unless the property being updated has a value of null).


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

[View full API reference](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons~1%7Bid%7D/patch)

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

Important
**Regional Availability:**

* **Germany:** The credit record is required. Information is retrieved from SCHUFA (German credit bureau).
* **France, Italy, Spain:** A credit record is **not** required. Instead, creating a tax identification for the customer substitutes this requirement.


### 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**


```shell
POST /v1/persons/{person_id}/credit_records
```

* [API Reference: Create retail credit record](/api-reference/lending/credit-record/#operation/PersonCreditRecordWeb.V1.CreditRecords.CreateOperation)


**Freelancers**


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

* [API Reference: Create freelancer credit record](/api-reference/lending/credit-record/#operation/PersonCreditRecordWeb.V1.CreditRecords.CreateFreelancerOperation)


### GET Retrieve a credit record

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

**Request URL**


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

**Expiry Logic:**
If the `status` of the retrieved credit record is `expired`, you must create a new record for the customer before proceeding with a loan application.

* [API Reference: Retrieve credit record](/api-reference/lending/credit-record/#operation/PersonCreditRecordWeb.V1.CreditRecords.ShowOperation)


## 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**


```shell
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` (in case of two-step scoring) or `account_snapshot_pending` (in case of one-step scoring), and the remaining attributes, which will be populated during the application lifecycle.

[View full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Freelancer.Applications.CreateOperation)

**Scoring**

This API call automatically triggers Solaris' automated credit scoring system, which scores the application and provides its decision on the overdraft application.

**Approved application**

If Solaris scorer approves the application, the application status changes to `account_snapshot_pending`. In this case, notify the customer on your frontend and continue with the remaining steps in this guide.

**Rejected application**

In case of rejection, the application status changes to `rejected`. Notify the customer on your frontend and abort the process.

### 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](#freelancer-overdraft-application-status).

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

**Request URL**


```json
GET /v1/persons/{person_id}/overdraft_applications/{overdraft_application_id}
```

[View full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Freelancer.Applications.ShowOperation)

### Application status flow

The following diagram describes the status flow of a freelancer overdraft application:

Diagram: Freelancer overdraft application flow
## Step 4: Create account snapshot

In this step, you must create an account snapshot for the customer and link it to their overdraft application.

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


```shell
POST /v1/persons/{person_id}/account_snapshots
```

* [API Reference: Create snapshot](/api-reference/lending/account-snapshot/#operation/AccountSnapshotWeb.V1.AccountSnapshots.CreateOperation)


### Method 1: FinTecSystems (FTS)

Use this method to integrate the FTS wizard.

1. Integrate the FTS wizard in your solution (see [FTS Documentation](https://docs.fintecsystems.com/)).
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:**

**Response:**

### Method 2: Finreach

Use this method to integrate the FinX widget.

1. Integrate the FinX widget (see [FinX Documentation](https://docs.finx.finleap.cloud/#section/Native-Mobile-App-Integration)).
2. Call the endpoint with `source: FINREACH`.
3. Redirect the customer to the URL provided in the `location` field.


**Request:**

**Response:**

### 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:**

### 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:**

**Response:**

### GET Retrieve account snapshot

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

**Request URL**


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

* If the status is `expired`, you must create a new snapshot.
* Subscribe to the `ACCOUNT_SNAPSHOT` webhook for status updates.


* [API Reference: Retrieve snapshot](/api-reference/lending/account-snapshot/#operation/AccountSnapshotWeb.V1.AccountSnapshots.ShowOperation)


#### 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:**


```shell
PUT /v1/persons/{person_id}/overdraft_applications/{overdraft_application_id}/account_snapshot
```

[View full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Freelancer.Applications.LinkAccountSnapshotOperation)

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


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

[View full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Freelancer.Overdrafts.CreateOperation)

### GET Retrieve overdraft

This endpoint returns all the details of an existing consumer overdraft, assigned to the person with the `person_id` in the request URL. Additionally, subscribe to the webhook event `OVERDRAFT` to receive status updates about the overdraft. For a list of possible values and their descriptions, check the [Appendix](#freelancer-overdraft-status).

The webhook event sends status updates only. You have to call the `GET` method for the full overdraft details.

**Request URL**


```shell
GET /v1/persons/{person_id}/overdrafts/{overdraft_id}
```

[View full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Freelancer.Overdrafts.ShowOperation)

As the interest accrual rate could change from time to time, we encourage you to subscribe to the webhook `FREELANCER_OVERDRAFT_INTEREST_RATE_CHANGE`. This allows you to get the latest interest information and update the information in your frontend without calling the GET Retrieve overdraft endpoint.

## Step 6: 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 (Optional)

For specific overdraft-related events, you can monitor the account, implement specific event triggers, and provide pre-defined messages to the user.

For example, you can 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 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).


### Account closure for accounts with an overdraft

In case of [Account Closure Requests (ACR)](/guides/compliance/account-closure) for accounts with an attached overdraft, you must first terminate the overdraft before initiating the ACR process.

### Overdrafts in statements of account & bank statements

Each [statement of account](/guides/digital-banking/account-management#statements-of-account) and [bank statement](/guides/digital-banking/account-management#bank-statements) generated for customers with overdrafts will contain the following overdraft information for the statement period:

* `overdraft_facility`: Overdraft facility that has been granted to the customer.
* `overdraft_rate`: The increased interest rate applied when going below the granted overdraft facility.
* `interest_accrual_rate`: The daily rate at which interest is accrued on the used amount of an overdraft.
* `interest_accrued`: The interest accrued, in Euro cents.


[See the Account management guide for more information.](/guides/digital-banking/account-management#statements-of-account)

### Overdrafts termination

To terminate a freelancer overdraft, you can trigger the termination request by calling the following endpoint:

#### POST Terminate a freelancer overdraft

This endpoint initiates a termination request for an existing freelancer overdraft.


```shell
POST /v1/persons/{person_id}/overdrafts/{overdraft_id}/terminate
```

[View full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Freelancer.Overdrafts.TerminateOperation)

* Solaris performs certain validations on termination requests using this endpoint. The customer's account must be **positive** or **zero** after booking the accrued interest from the overdraft usage on the account.
* If the account has negative balance, the request will be rejected. In this case, you can initiate a request to our support team by creating a JIRA ticket as explained in the previous section.


## Next steps

Congratulations! You have 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](/guides/lending) page.

### Useful resources

Check the following links for additional related guides and API reference documentation.

* [Freelancer Overdrafts API Reference documentation](/api-reference/lending/overdrafts/#tag/Freelancer-Overdrafts)
* [Overdrafts overview](/guides/lending/overdrafts)


## 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. |
| `terminated` | Overdraft is terminated. |