# Consumer Overdrafts

This guide explains how to integrate Solaris' Overdraft product for retail customers (Consumers) into your solution.

## Introduction

### Product specifications

Consumer 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 retail credit scoring system to make informed credit decisions on consumer 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 credit checks done throughout the application lifecycle, the scorer estimates the probability of default (PD) and then determines whether to offer an overdraft to the customer. It also determines the amount and interest rate to be 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 sequence diagram gives an overview of the integration flow for the Consumer Overdrafts solution:

![Diagram: Consumer overdraft flow](/assets/consumer-overdraft-flow.0f7b8fc0e79332cda86e8bce0ffa44dbe8470b11460cecef1ae4d22a2ee82c15.da581abd.svg)

Integrate Solaris' Consumer Overdrafts by completing the following steps:

| Stage | Step | Description |
|  --- | --- | --- |
| Credit record | [Step 1](#step-1-create-consumer-credit-record) | Collect the customer's consent to performing credit checks and create a credit record for the customer. |
| Overdraft application | [Step 2](#step-2-create-consumer-overdraft-application) | Collect the required information from your customers on your frontend and create an overdraft application. |
| Overdraft documents | [Step 3](#step-3-download-secci-and-conditions-form) | If the application is approved and the status changes to `offered`, download the SECCI form and the overdraft terms and conditions and share it with the customer as a PDF. Once reviewed by the customer, record the customer's consent to the terms and conditions and the overdraft loan agreement as a UTC timestamp. |
| Overdraft creation | [Step 4](#step-4-create-consumer-overdraft) | 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 5](#step-5-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/).

- [CONSUMER_OVERDRAFT](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/consumer_overdraft_application/post)
- [CONSUMER_OVERDRAFT_APPLICATION](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/consumer_overdraft/post)
- [OVERDRAFT_LIMIT_CHANGE](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/overdraft_limit_change/post)


## Step 1: Create consumer credit record

In your frontend flow, collect the customer's consent to performing credit checks and account snapshot. Afterward, 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 2: Create consumer overdraft application

In this step, collect the mandatory information from the customer in your sign-up flow and pass it to Solaris by creating a consumer overdraft application.

### POST Create consumer overdraft application

Call this endpoint to create a consumer overdraft application for the customer with the `person_id` specified in the request URL. The overdraft application includes all the required information about the customer and links to other mandatory resources, such as `credit_record` or `account_iban`.

**Mandatory properties:**

Add the following mandatory properties in the request body:

- `credit_record_id`
- `net_income_amount`
- `identification_id`
- `employment_status`
- `account_iban`


**Optional properties:**

- `partner_requested_limit`: A field to request a specific overdraft limit amount. Add the amount in Euro, cents.
- `minimum_credit_risk_criteria`: An object that contains different credit risk related properties that are required for the credit scoring system. This field could be mandatory depending on your use case. If applicable, Solaris will share with you the fields that you must collect from the customer.


**Request URL**


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

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

[Click here to view the full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Consumer.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 `offered`. 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 aboard the process.

### GET Retrieve consumer overdraft application

This endpoint returns the current status and details of an existing consumer overdraft application. For a list of possible values of the application `status` and their descriptions, check the [appendix](#consumer-overdraft-application-statuses).

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

**Request URL:**


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

[Click here to view the full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Consumer.Applications.ShowOperation)

### Application status flow

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

![Diagram: Consumer overdraft application flow](/assets/consumer-overdraft-application-status-flow.388fb53cfde2a273e5d9d91a76ba1fe5e6281baf5179d03aba5a583dfb476a8d.da581abd.svg)

## Step 3: Download SECCI and conditions form

In this step, you must download the following documents and share them with the customer to review:

- A SECCI form: an overview of the final overdraft offer.
- Overdraft conditions: the terms and conditions of the overdraft.


### GET Download SECCI form

**Request URL**


```shell
GET /v1/persons/{person_id}/consumer_overdraft_applications/{application_id}/pre_contract
```

[Click here to view the full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Applications.DownloadPreContractOperation)

### GET Download overdraft conditions

**Request URL**


```shell
GET /v1/persons/{person_id}/consumer_overdraft_applications/{application_id}/conditions
```

[Click here to view the full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Applications.DownloadConditionsOperation)

## Step 4: Create consumer overdraft

After Solaris approves the overdraft application, you must complete the following steps:

1. Inform the customer of the approval on your frontend, and send the documents you downloaded in [step 3](#step-3-download-secci-and-conditions-form) to the customer to review.
2. Collect and record the customer's consent to the overdraft's special terms and conditions and  agreement as a UTC timestamp. The consent must NOT be older than 24 hours.
3. Create the overdraft on the customer's account by calling [PUT Create the overdraft](#put-create-the-overdraft).


### PUT Create the overdraft

Call this endpoint to create the overdraft on the customer's account. You must include the customer's `application_id` and `person_id` in the request URL. Additionally, include the following mandatory properties in the request body:

- `account_id`: The ID of the customer's account at Solaris.
- `tnc_accepted_at`: The UTC timestamp from when the customer's accepted the overdraft's terms and conditions and agreement.


**Request URL**


```shell
PUT /v1/persons/{person_id}/consumer_overdraft_applications/{overdraft_application_id}/overdraft
```

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

[Click here to view the full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Consumer.Overdrafts.CreateOperation)

### GET Retrieve consumer 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 `CONSUMER_OVERDRAFT` to receive status updates about the overdraft.

Please note that 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}/consumer_overdrafts/{overdraft_id}
```

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](#consumer-overdraft-statuses).

[Click here to view the full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Consumer.Overdrafts.ShowOperation)

### GET Retrieve all consumer overdrafts

This endpoint returns all consumer overdrafts for all of your customers.

**Request URL**


```shell
GET /v1/persons/consumer_overdrafts
```

[Click here to view the full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Consumer.Overdrafts.IndexOperation)

## Step 5: 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.](https://docs.solarisgroup.com/guides/digital-banking/account-management/#statements-of-account)

### Consumer overdraft limit changes

You can request an overdraft limit change either an increase or a decrease of limit by using the following endpoints. Solaris will assess the request and either approve it or reject it.

The following diagram shows the process flow of an overdraft limit change request:

![Diagram: Consumer overdraft limit change flow](/assets/consumer-overdraft-limit-change-flow.26a4b72faeb6454126887d121d4fe82732371ef8b6a875132bb7a0bcf8e151e4.da581abd.svg)

#### POST Request overdraft limit change

Call this endpoint to request a limit change and specify the amount of the requested limited and reason for the request.


```shell
POST /v1/persons/{person_id}/consumer_overdrafts/{overdraft_id}/limit_changes
```

[Click here to view the full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Consumer.LimitChanges.CreateOperation)

Once approved the status will change to `tnc_pending`. Afterward, you need to generate new SECCI form and terms and conditions with the new overdraft limit and get the customer's signature on the new documents.

#### GET Retrieve consumer overdraft limit change request

This endpoint returns the current status and details of an existing consumer overdraft limit change request. For a list of possible values of the application `status` and their descriptions, check the [appendix](#consumer-overdraft-limit-change-request-statuses).

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

**Request URL:**


```
GET /v1/persons/{person_id}/consumer_overdrafts/{overdraft_id}/limit_changes/{limit_change_id}
```

[Click here to view the full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Consumer.LimitChanges.ShowOperation)

#### Application status flow

The following diagram describes the status flow of a consumer overdraft limit change request:

![Diagram: Consumer overdraft limit change request status flow](/assets/consumer-overdraft-limit-change-request-status-flow.a77f277c0afa1184a9490211496267d22801134f5f4f8b7b1840c1a12f7f9388.da581abd.svg)

#### GET Download SECCI form for a limit change

Call the following endpoint to generate a new SECCI form with the new limit and share it with the customer to review.


```shell
GET /v1/persons/{person_id}/consumer_overdrafts/{overdraft_id}/limit_changes/{limit_change_id}/pre_contract
```

[Click here to view the full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Consumer.LimitChanges.DownloadPreContractOperation)

#### GET Download the overdraft conditions for a limit change

Call the following endpoint to generate new overdraft terms and conditions with the new limit and share it with the customer to sign, and record the customer's signature as UTC timestamp.


```shell
GET /v1/persons/{person_id}/consumer_overdraft_applications/{application_id}/conditions
```

[Click here to view the full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Applications.DownloadConditionsOperation)

#### PUT Activate the new overdraft limit

Call this endpoint to attach the new limit to the customer's account and add the UTC timestamp of the customer's signature in the request body.


```shell
PUT /v1/persons/{person_id}/consumer_overdrafts/{overdraft_id}/limit_changes/{limit_change_id}
```

[Click here to view the full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Consumer.LimitChanges.PutOperation)

### Consumer overdrafts termination

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

#### POST Terminate a consumer overdraft

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


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

[Click here to view the full API reference](/api-reference/lending/overdrafts/#operation/OverdraftWeb.V1.Consumer.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.


## What's next?

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

- [Consumer Overdrafts API Reference documentation](/api-reference/lending/overdrafts/#tag/Consumer-Overdrafts)
- [Overdrafts overview](/guides/lending/overdrafts)
- [Person Onboarding Guide](/guides/get-started/digital-banking/onboard-person)


## Appendix I: Enums

### Consumer overdraft application statuses

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

| Status | Description |
|  --- | --- |
| `scoring_pending` | Solaris successfully received the overdraft application and is assessing and scoring the application. |
| `offered` | Credit checks were successful, and Solaris approved the overdraft application. |
| `rejected` | Credit checks failed, and Solaris rejected the overdraft application. |
| `overdraft_created` | The overdraft is created on the customer's account. |
| `deleted` | The overdraft application is deleted. Solaris deletes all failed applications in compliance with GDPR regulations. |


### Consumer overdraft statuses

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. |
| `conditions_pending` | Interest conditions are pending and yet to be set by Solaris. |
| `limit_pending` | Overdraft limit is pending and yet to be set by Solaris. |
| `attached` | Overdraft is attached to the customer's account. |
| `defaulted_pending` | A default is active on the overdraft and the dunning process starts. |
| `conditions_termination_pending` | Dunning process started regarding a default and termination conditions are yet to be set. |
| `termination_pending` | Termination conditions are set. |
| `terminated` | Overdraft is terminated. |


### Consumer overdraft limit change request statuses

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

| Status | Description |
|  --- | --- |
| `requested` | The overdraft limit change request is created and currently being processed by Solaris. |
| `tnc_pending` | The overdraft limit change request is approved. You need to generate new SECCI form and terms and conditions with the new limit. |
| `tnc_accepted` | The customer has accepted the new overdraft terms and conditions. |
| `conditions_pending` | Interest conditions are pending and yet to be set by Solaris. |
| `limit_pending` | Overdraft limit is pending and yet to be set by Solaris. |
| `attached` | Overdraft limit is attached to the customer's account. |
| `cancelled` | Overdraft limit change request is cancelled. |
| `expired` | Overdraft limit change request has expired. |