# Decoupled cards for consumers

Solaris Decoupled Cards enable customers to benefit from a modern debit card without opening a new bank account or manually transferring funds to use the card to make purchases.

This guide explains the integration process of decoupled cards for consumers, including key concepts and the necessary endpoints for creating, activating, and servicing decoupled cards.

## Introduction

### Product specifications

A decoupled card is a debit card with an attached credit limit set according to a risk-based scoring system and linked to the customer's external bank account (i.e., the reference account). Customers can use the available limit to make purchases using the card. The negative balance is settled daily from the customer's external reference account via SEPA Direct Debit (SDD).

Decoupled cards are subject to account and transaction fees, and they can be issued in physical or virtual form. They are currently available to **retail customers in Germany** with a limit from EUR 100 to EUR 1,000, depending on the customer's credit score.

Due to its limited functionality, a decoupled card is NOT considered a credit card or a payments account.

### User journey

A decoupled card combines a card, account, and credit limit. The user journey looks as follows:

1. The customer applies for a decoupled card with Solaris and agrees to the terms and conditions, credit checks, and account snapshot.
2. After passing the credit checks stage, the customer is offered a decoupled card with a specific credit limit (i.e., an overdraft limit).
3. The customer goes through the customer identification process (KYC).
4. After a successful identification, you will create an internal bank account (with type `DECOUPLED_CARD_PERSONAL`) for the customer. The offered credit limit is attached to this account and linked to the associated debit card.
  * **Note:** This account is only used in the context of a decoupled card and is not considered a full payments account.
5. The customer specifies an external reference account and signs a SEPA Direct Debit (SDD) mandate, which authorizes Solaris to debit the reference account with an SDD whenever the decoupled card credit limit is used. The SDD amount equals the used amount.
6. Whenever the customer uses the card credit limit to make a purchase or withdrawal, the internal account balance goes negative. Afterward, an SDD of the used amount will be debited from the reference account on the same day and transferred to the customer's internal account to settle the negative balance.


The following diagram gives a general overview of the decoupled cards onboarding process:

Diagram: Decoupled Cards process flow
### Credit scoring

Solaris uses an automated credit scorer to analyze and score consumer decoupled card applications. The credit scorer uses different information to score applications, including credit records, account snapshots, and other necessary information.

The scorer performs different credit checks throughout the application lifecycle, such as:

* **Initial scoring:** Checks the credit record obtained from external credit bureaus, such as SCHUFA.
* **Verification:** Checks the account snapshot to verify the financial information provided in the decoupled card application.


### Accounts

A decoupled card involves different bank accounts:

1. **Reference account**: The customer's external bank account from which the SDD is pulled to settle the internal account balance when the customer makes purchases with the decoupled card.
  * **Note:** Customers can have multiple reference accounts tied to their decoupled card. Consult your Partner Manager for more information about setting up multiple reference accounts.
2. **Internal account**: An internal Solaris account created for a decoupled card. The overdraft (i.e., the credit limit available on the card) is attached to this account. Solaris credits the funds from the customer's reference account to this account via SDD to settle any negative balance.
3. **(Optional) Round-up account**: The customer can opt for a round-up account associated with the decoupled card. The customer specifies a round-up amount for each purchase (e.g., rounding up the purchase amount to the nearest value). In this case, the SDD includes the purchase amount (transferred to the internal account) and the round-up amount (transferred to the round-up account).
  * **Note:** This account can only be used in the manual SDD orchestration setup.


### Decoupled card usage

The customer can use the decoupled card for the following use cases:

* Card payments and ATM cash withdrawals using the credit limit available on the internal account.
* Topping up the card's account with cash by transferring money from their external reference account to the internal card account.
* Transferring any **positive** balance on the card's account back to their reference account.


Note
Customers **cannot** transfer cash from the credit limit balance on the internal account to their reference account.

### SDD orchestration

Solaris uses [SEPA Direct Debit (SDD)](/guides/digital-banking/sepa-transfers/sepa-direct-debit-transfer/) to settle the internal account balance from the customer's external reference account. The SDD amount equals the amount the customer used from the card's credit limit.

Depending on your needs, you can choose between two options for how the SDD should be orchestrated:

* **Automatic SDD orchestration**: In this setup, Solaris handles the money flow between the reference account and the internal account. The SDD is triggered automatically each day for any negative balance. You do not need to implement any endpoints.
* **Manual SDD orchestration**: In this setup, you can have more control over when the SDD is triggered and the amount to be debited from the customer's reference account. However, this setup requires additional configurations. Consult your Partner Manager for more information.


## System prerequisites

Before starting the onboarding process, please implement the following prerequisites:

### 1. Technical setup

Before starting, ensure your environment is configured for the **Digital Banking** product scope.

* **Authentication:** Retrieve your client credentials and set up your OAuth flow.
* **Webhooks:** Configure your endpoint to receive event notifications (e.g., incoming transfers, status changes).


[View the Technical Setup Guide](/guides/get-started/technical-setup)

### 2. Legal & Compliance screens

You must integrate specific consent screens into your signup flow *before* initiating the API onboarding process.

**Required Screens:**

1. **Terms & Conditions:** Collect explicit consent to Solaris T&Cs.
2. **Customer Information:** verify personal details.
3. **Economic Interest:** Confirm the customer is acting on their own behalf.
4. **Tax Information:** Collect Tax ID (required for Germany).
5. **FATCA/CRS:** Determine US tax liability.
6. **PEP Declaration:** Self-declaration for Politically Exposed Persons (Required for FR, IT, ES).


**Data Storage:**
For every consent screen, you must capture a **UTC timestamp** (e.g., `2023-10-27T10:00:00Z`). These timestamps are mandatory fields when creating the `person` resource.

| Consent Type | API Field (Person Resource) |
|  --- | --- |
| Terms & Conditions | `terms_conditions_signed_at` |
| Data Processing | `data_terms_signed_at` |
| Economic Interest | `own_economic_interest_signed_at` |
| FATCA/CRS | `fatca_crs_confirmed_at` |


[View the Legal Screens Guide](/guides/get-started/onboarding-requirements/1-legal-compliance-screens)

## Integration overview

Onboard retail customers for decoupled cards by completing the following steps:

| Category | Step | Description |
|  --- | --- | --- |
| **Customer registration** | [Step 1](#step-1-collect-customer-data-and-create-person-resource) | Collect the mandatory data points and create a person resource for your customer. |
| **Customer registration** | [Step 2](#step-2-create-and-verify-mobile-number) | Create and verify the customer's mobile number. |
| **Tax information** | [Step 3](#step-3-create-customer-tax-identification) | Collect the customer's tax information and create a tax identification resource. |
| **SDD collection application** | [Step 4](#step-4-create-person-credit-record) | Create a credit record for the customer. The credit record is mandatory for the credit scorer. |
| **SDD collection application** | [Step 5](#step-5-create-sdd-collection-application) | Create an SDD collection application for the customer and include the credit record ID created in the previous step. |
| **SDD collection application** | [Step 6](#step-6-create-account-snapshot) | Create an account snapshot for the customer and attach it to the SDD collection application. |
| **Customer identification** | [Step 7](#step-7-complete-the-customer-identification-and-due-diligence-process) | **7.1.** Create and trigger the [customer identification process (KYC)](#71-customer-identification) and redirect the customer to complete the process with the chosen provider. **7.2.** Ensure that the customer passes the [customer due diligence process](#72-customer-due-diligence-cdd) before proceeding with the following steps. |
| **Accounts creation** | [Step 8](#step-8-set-up-customer-internal-account) | Create an internal decoupled card account for the customer and link it to the SDD collection application. |
| **Accounts creation** | [Step 9](#step-9-create-reference-account-and-sdd-mandate) | Create a reference account and link it to the decoupled card internal account, as well as the SDD mandate, to enable pulling the SDD from the reference account. |
| **Card creation** | [Step 10](#step-10-create-and-activate-decoupled-card) | Create and activate the decoupled card for the customer. |
| **Servicing decoupled cards** | [Step 11](#step-11-servicing-decoupled-cards) | Implement all endpoints related to servicing decoupled cards. |


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

### Webhooks

Subscribe to the following webhook events to automate your integration. For implementation details, check the [webhooks documentation](/api-reference/webhooks/).

### Identity and person data

* [`IDENTIFICATION`](/api-reference/onboarding/webhooks/webhook-events/paths/identification/post)
* [`PERSON_CHANGED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_changed/post)
* [`PERSON_DELETED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_deleted/post)
* [`PERSON_MOBILE_NUMBER_CREATED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_mobile_number_created/post)
* [`PERSON_MOBILE_NUMBER_DELETED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_mobile_number_deleted/post)
* [`PERSON_TAX_IDENTIFICATION_CHANGED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_tax_identification_changed/post)


### Accounts and bookings

* [`BOOKING`](/api-reference/onboarding/webhooks/webhook-events/paths/booking/post)
* [`ACCOUNT_BLOCK`](/api-reference/onboarding/webhooks/webhook-events/paths/account_block/post)
* [`ACCOUNT_CLOSURE`](/api-reference/onboarding/webhooks/webhook-events/paths/account_closure/post)
* [`ACCOUNT_CLOSURE_REQUEST`](/api-reference/onboarding/webhooks/webhook-events/paths/account_closure/post)
* [`POTENTIAL_ACCOUNT_BLOCKING`](/api-reference/onboarding/webhooks/webhook-events/paths/potential_account_blocking/post)
* [`POSTBOX_ITEM_CREATED`](/api-reference/onboarding/webhooks/webhook-events/paths/postbox_item_created/post)


### Cards

* [`CARD_LIFECYCLE_EVENT`](/api-reference/onboarding/webhooks/webhook-events/paths/card_lifecycle_event/post)
* [`CARD_AUTHORIZATION`](/api-reference/onboarding/webhooks/webhook-events/paths/card_authorization/post)
* [`CARD_AUTHORIZATION_DECLINE_V2`](/api-reference/onboarding/webhooks/webhook-events/paths/card_authorization_decline_v2/post)
* [`CARD_AUTHORIZATION_RESOLUTION`](/api-reference/onboarding/webhooks/webhook-events/paths/card_authorization_resolved/post)
* [`CARD_FRAUD_CASE_PENDING`](/api-reference/onboarding/webhooks/webhook-events/paths/card_fraud_case_pending/post)
* [`CARD_FRAUD_CASE_TIMEOUT`](/api-reference/onboarding/webhooks/webhook-events/paths/card_fraud_case_timeout/post)


### Compliance and seizures

* [`PERSON_SEIZURE_CREATED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_seizure_created/post)
* [`PERSON_SEIZURE_DELETED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_seizure_deleted/post)
* [`PERSON_SEIZURE_FULFILLED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_seizure_fulfilled/post)
* [`PERSON_SEIZURE_UPDATED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_seizure_updated/post)


### Authentication

* [`SCA_CHALLENGE`](/api-reference/onboarding/webhooks/webhook-events/paths/sca_challenge/post)


* [ACCOUNT_LIMIT_CHANGE](/api-reference/onboarding/webhooks/webhook-events/paths/account_limit_change/post)
* [ACCOUNT_SNAPSHOT](/api-reference/onboarding/webhooks/webhook-events/paths/account_snapshot/post)
* [SDD_COLLECTION_APPLICATION](/api-reference/onboarding/webhooks/webhook-events/paths/sdd_collection_application/post)
* [MESSAGE](/api-reference/onboarding/webhooks/webhook-events/paths/message/post)


### Mandatory features

You must integrate all the mandatory features for Digital Banking & Cards highlighted in the [Onboarding requirements guide](/guides/get-started/onboarding-requirements/2-data-collection/#customer-data-resource-types) before going live with your solution.

## Step 1: Collect customer data and create person resource

In this step, you must 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/webhook-events/paths/person_changed/post)
- [`PERSON_DELETED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_deleted/post)


Important points about data collection
- Review the special requirements in the [Onboarding requirements guide](/guides/get-started/onboarding-requirements/2-data-collection/#important-considerations-for-data-collection).
- Submit information exactly as it appears in official documents.
- **Sandbox Testing:** 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.
- **Privacy:** Do not use real personal data when testing in Sandbox.


#### POST Create person

Important points
- The mandatory data points required for retail customers may differ depending on the country in which you're opening the account. The following example outlines the mandatory fields for Germany. For information about other countries, please refer to the [Onboarding requirements guide](/guides/get-started/onboarding-requirements/2-data-collection/#retail-customers-b2c)


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`: This field is only used to pass the mobile number to our KYC provider IDnow for the Videoident KYC flow. To create and verify a mobile number for your customer, you need to use the dedicated [mobile number endpoints](https://docs.solarisgroup.com/api-reference/onboarding/persons/#tag/Person-mobile-numbers).
- `birth_date`
- `birth_city` (must be a valid city)
- `birth_country`
- `nationality`
- `employment_status`
- `fatca_relevant`
- `fatca_crs_confirmed_at`
- `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`


Important
**Restricted Updates:**

* Fields not mentioned in this list can only be updated via Customer Support.


**Freelancer & Self-Employed Requirements (B2C):**

* If a customer changes their `employment_status` to `FREELANCER` or `SELF_EMPLOYED`, you must include **one** of the following in the request to avoid an error:
  1. The customer's `nace_code` (Recommended for data quality).
  2. Set `industry` and `industry_key` to `null`.


**Request URL**


```shell
PATCH /v1/persons/{id}
```

**Request example**

* [API Reference: Update person](/api-reference/onboarding/persons/#tag/Persons/paths/~1v1~1persons~1%7Bid%7D/patch)


## Step 2: Create and verify mobile number

In this step, collect the customer's mobile number in your sign-up flow and then create a mobile number resource and verify it by sending an SMS OTP to the customer's mobile number. Afterward, the customer enters the received OTP in your frontend to verify their number.

### Mobile number resource

Creating and verifying a mobile number for your customer is a crucial step in the customer onboarding process. With a verified mobile number, customers can use SMS OTPs to complete two-factor authentication (2FA) challenges, which is a requirement for Strong Customer Authentication (SCA).

Info
In some use cases (e.g., stand-alone integrations), the mobile number is verified during the identification process.

### API reference

Visit the following link to find all the endpoints related to the mobile number resource, including related properties and examples.

- [Mobile number resource API reference](/api-reference/onboarding/persons/#tag/Person-mobile-numbers)


**Related webhook events**

- [PERSON_MOBILE_NUMBER_CREATED](/api-reference/onboarding/webhooks/webhook-events/paths/person_mobile_number_created/post)
- [PERSON_MOBILE_NUMBER_DELETED](/api-reference/onboarding/webhooks/webhook-events/paths/person_mobile_number_deleted/post)


Testing static values
To test the following endpoints on Sandbox, you can use the following static values:

- Mobile number: `+15550101`
- SMS OTP: `212212`


#### POST Create mobile number

Collect the customer's mobile number and pass it to Solaris using the following API call. You must include the customer's `person_id` in the request URL.

**Request URL**


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

**Request example**


```json
{
  "number": "+15550101"
}
```

**Response example**

The API returns a `mobile_number` resource with a unique `id` and attaches it to the `person` resource.


```json
{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": false
}
```

[Click here to view the full API reference.](/api-reference/onboarding/persons/#tag/Person-mobile-numbers/paths/~1v1~1persons~1%7Bperson_id%7D~1mobile_number/post)

#### POST Authorize mobile number

Use the following endpoint to verify the ownership of the provided mobile phone number. The endpoint initiates a one-time-password (OTP) flow: Solaris sends a six-digit OTP to the customer's number, and then they must enter it in your UI.

**Request URL**


```shell
POST /v1/persons/{person_id}/mobile_number/authorize
```

**Request example**


```json
{
  "number": "+15550101"
}
```

**Response example**


```json
{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": false
}
```

[Click here to view the full API reference.](/api-reference/onboarding/persons/#tag/Person-mobile-numbers/paths/~1v1~1persons~1%7Bperson_id%7D~1mobile_number~1authorize/post).

#### POST Confirm mobile number

Use this endpoint to submit the SMS OTP the customer received on their mobile number to finalize the mobile number authorization process. You must add the customer's `number` and `token` (i.e., the SMS OTP) in the request body. Afterward, the mobile number will be `verified` and can be used in the context of Strong Customer Authentication (SCA).

**Request URL**


```shell
POST /v1/persons/{person_id}/mobile_number/confirm
```

**Request example**


```json
{
  "number": "+15550101",
  "token": "212212"
}
```

**Response example**


```json
{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": true
}
```

[Click here to view the full API reference.](/api-reference/onboarding/persons/#tag/Person-mobile-numbers/paths/~1v1~1persons~1%7Bperson_id%7D~1mobile_number~1confirm/post)

For more information about how to manage mobile numbers (e.g., changing or deleting a number), check the related [mobile number management guide](/guides/digital-banking/mobile-number-management).

## Step 3: Create customer tax identification

In this step, collect the relevant [tax information](/guides/get-started/onboarding-requirements/3-tax-information/) from the customer and create a tax identification resource for them.

### API reference

Important points about tax information
Submitting the tax information of your customers is a requirement to open a bank account in all of Solaris branches. However, note the following:

* You can open the bank account for customers in Germany (DE branch) before they provide tax information. However, you must submit the customer's tax information to Solaris within **90 days** of opening the account. Otherwise, Solaris will block the customer's account with the reason `MISSING_TAX_INFORMATION` until you submit the required tax information.
* If a customer has multiple tax residencies (i.e., taxable in multiple countries), you must create a separate tax identification resource for each tax residency and specify **only** one of them as `primary`.
* The first `tax_identification` to be submitted for a `person` or a `business` must be the primary tax identification. If another `tax_identification` with the value of `primary` set to `true` is created, it will set the `primary` value of the previously created `tax_identification` to `false`.
* A `person` or `business` may only have one `tax_identification` per `country`.
* When creating a `tax_identification`, explicitly collect the `country` value from the user and do not default to their physical residence (i.e., the `country` property of the `person` resource).
* Check the [Onboarding requirements guide](/guides/get-started/onboarding-requirements/3-tax-information#tax-identification-number-tin-per-country) for more information about the TIN requirements per country.


For a complete list of endpoints, properties, and examples related to the `person tax identification` resource, visit the following links:

- [Person tax identifications API reference](/api-reference/onboarding/persons/#tag/Person-tax-identifications):
  - [POST Create person tax identification](/api-reference/onboarding/persons/#tag/Person-tax-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1tax_identifications/post)
  - [GET Retrieve person tax identification ](/api-reference/onboarding/persons/#tag/Person-tax-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1tax_identifications~1%7Bid%7D/get)
  - [PATCH Update person tax identification ](/api-reference/onboarding/persons/#tag/Person-tax-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1tax_identifications~1%7Bid%7D/patch)


**Related webhook events**

- [PERSON_TAX_IDENTIFICATION_CHANGED](/api-reference/onboarding/webhooks/webhook-events/paths/person_tax_identification_changed/post)


#### POST Create person tax identification

Call this endpoint to create a person tax identification for the customer with the `person_id` specified in the request URL. Collect the following tax information from your customers and pass them to Solaris in the request body:

- `number`
- `country`
- `primary`


If the customer has not submitted their TIN to your solution yet (i.e., the value of `number` is `null`), then include the following properties in the request:

- `reason_no_tin`: Possible values are `NOT_ASSIGNED_YET`, `NOT_ASSIGNED_BY_COUNTRY`, `OTHER`.
- `reason_description`: Applies only if the `reason_no_tin` is `OTHER`.
- `tax_id_type`: (Only for Spain) Possible values are `NIE` and `NIF`.


**Request example:**


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

[Click here to view the full API reference.](/api-reference/onboarding/persons/#tag/Person-tax-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1tax_identifications/post)

### Tax ID testing data

You can use the following test values for the TIN to test these endpoints on Sandbox:

| Country | TIN testing values |
|  --- | --- |
| DE | 48954371207 |
| FR | 3023217600053 |
| IT | SSSNNN31B28X000C |
| ES | Test data can be generated from this [website](https://testingdatagenerator.com/doi.html) |


## Step 4: Create person 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 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 5: Create SDD collection application

In this step, you must create a SEPA Direct Debit (SDD) collection application for the customer and include the credit record ID created in the previous step.

### POST Create SDD collection application

This endpoint creates an SDD collection application and assigns it to the person with the `person_id` specified in the request URL. In addition, you must include the `credit_record_id` you created in the previous step in the request body.

**Request URL**


```json
//POST /persons/{person_id}/sdd_collection_applications
{
  "credit_record_id": "fbb7d15fa4c54ba0b077592665ef04a4ccrd"
}
```

The API will return an object containing a unique ID for the SDD collection application as well as the application's `status`, which is initially set to `initial_scoring_pending`. You must use this `id` in later API calls as the value of `sdd_collection_application_id`.

**Scoring**

This API call automatically triggers the credit scoring system, which scores the application and credit record and provides its decision in the `decision` field.

**Rejected application**

In case of rejection, the application `status` changes to `rejected` and `decision` will be set to `REJECTED`. You must abort the onboarding process in this case.

**Approved application**

If Solaris' scorer approves the SDD application, the application `status` changes to `account_snapshot_pending` and the `decision` value will change to `OFFERED`. Afterward, you can proceed to [Step 6](#step-6-create-account-snapshot) to create an account snapshot.

[View POST Create SDD collection application API reference](/api-reference/digital-banking/sepa-transfers/#tag/SDD-Collection-Applications/paths/~1v1~1persons~1%7Bperson_id%7D~1sdd_collection_applications/post)

### GET Retrieve customer SDD collection application

Call this endpoint to retrieve a customer's SDD application and track the application lifecycle through the `status` field. Additionally, subscribe to the webhook event `SDD_COLLECTION_APPLICATION` to receive status updates about the application.

Check [Appendix I](#sdd-collection-application-status) for a list of possible values and descriptions for the `status` field. Additionally, check the application status flow [below](#application-status-flow).

**Request URL**


```shell
GET /persons/{person_id}/sdd_collection_applications/{sdd_collection_application_id}
```

[View GET Retrieve customer SDD collection application API reference](/api-reference/digital-banking/sepa-transfers/#tag/SDD-Collection-Applications/paths/~1v1~1persons~1%7Bperson_id%7D~1sdd_collection_applications~1%7Bsdd_collection_application_id%7D/get)

### Application status flow

The following diagram describes the status flow of an SDD application:

Diagram: SDD application flow
## Step 6: Create account snapshot

Once the application `status` changes to `account_snapshot_pending`, you need to create an account snapshot for the customer and link it to their SDD collection application.

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


If you are using Bankident to identify the customer, the account snapshot is automatically created within the payment verification step. Check the [Bankident guide](/guides/kyc/bankident) for more details.

#### PUT Link customer account snapshot to SDD collection application

After creating an account snapshot, call this endpoint to attach it to the SDD collection application by adding the `account_snapshot_id` to the request body.

**Request URL**


```json
// PUT /persons/{person_id}/sdd_collection_applications/{sdd_collection_application_id}/account_snapshot
{
  "account_snapshot_id": "0a3f28733f9a4842842aae2804f80eb4snap"
}
```

Once linked, the application status will change to `account_snapshot_verification_pending`. Calling this endpoint also sends a webhook notification on the `SDD_COLLECTION_APPLICATION` event.

Additionally, this action triggers the credit scoring system to perform the final verification step on the customer's bank account to determine the overdraft limit based on the customer's income, expenses, and recurring credit repayments. After successful verification, the application `status` changes to `offered`.

[View PUT Link customer account snapshot API reference](/api-reference/digital-banking/sepa-transfers/#tag/SDD-Collection-Applications/paths/~1v1~1persons~1%7Bperson_id%7D~1sdd_collection_applications~1%7Bsdd_collection_application_id%7D~1account_snapshot/put)

## Step 7: Complete the customer identification and due diligence process

In this step, you must trigger the Know Your Customer (KYC) process for your customer and ensure they pass all the mandatory screening checks.

### 7.1 Customer identification

All customers must be successfully identified using a suitable KYC method to be onboarded for any of Solaris' products.

Solaris offers different identification methods based on the product, region, and customer type. You can use the following identification methods to identify customers for decoupled cards:

* [Bankident](/guides/kyc/bankident) (Only for customers with a German IBAN).
* [Video identification](/guides/kyc/videoident) (Only for customers with supported identification documents).


For an overview of the suitable KYC method per country, check the [Onboarding requirements guide](/guides/get-started/onboarding-requirements/5-kyc/#digital-banking--cards), and consult with your Partner Manager about the identification method tailored to your banking use case.

* The previous links will take you to the integration guide of each identification method. Go to the integration guide of your chosen identification method and complete the steps to identify your customer.
* Skip the preparation/setup steps in the identification guides, as they have already been covered here in this guide.


### 7.2 Customer due diligence (CDD)

* In addition to the identification process, Solaris runs different risk screening and customer vetting checks (i.e., Customer Due Diligence process) on new and existing customers.
* The result of this process is stored in different properties in the `person` resource.
* The status of all the CDD-related properties must be `green` for the customer to be onboarded.


For more information, check the [Customer Due Diligence guide](/guides/kyc/cdd).

## Step 8: Set up customer internal account

Important prerequisites
* Your customer must be successfully identified and screened before creating an account.
* The `status` of the SDD collection application must be `offered`.


In this step, you must create the internal account for the customer and attach the approved credit limit. Then, when the customer uses their decoupled card to make a purchase, the balance of this account will go negative, and the customer's external reference account will be debited in the amount of the negative balance. The SDD will be credited to this account for settlement.

The customer can top up this account and transfer any positive balance back to the reference account.

IMPORTANT
The internal account is **not** a full payments bank account and can only be used within the constraints of the decoupled card.

### Account opening process

To open an account for your customer, visit the following links to find more information about the account opening process.

For this product, you need to open an account with the type `DECOUPLED_CARD_CONSUMER`.

* [Account opening guide](/guides/digital-banking/account-opening/)
* [Account opening API reference](/api-reference/onboarding/account-creation/#tag/Account-opening)


### PUT Link internal account to SDD collection application

This endpoint attaches the created internal account to the SDD collection application. You must add the `account_id` returned from the previous process in the request body.

**Request URL**


```json
// PUT /persons/{person_id}/sdd_collection_applications/{sdd_collection_application_id}/account
{
  "account_id": "cb752d28214bcfea4c285de600ad0105cacc"
}
```

[View PUT Link internal account API reference](/api-reference/digital-banking/sepa-transfers/#tag/SDD-Collection-Applications/paths/~1v1~1persons~1%7Bperson_id%7D~1sdd_collection_applications~1%7Bsdd_collection_application_id%7D~1account/put)

Afterward, Solaris will attach the credit limit to the account, which the customer can use via the decoupled card.

## Step 9: Create reference account and SDD mandate

In this step, you must create a reference account for the customer. The reference account will be used as the account in the SDD mandate, from which Solaris will pull the SDD payments.

### Reference accounts API reference

Visit the following link to find all the endpoints related to the reference account resource, including related properties and examples.

- [Reference accounts resource API reference](/api-reference/digital-banking/account-management/#tag/Reference-accounts):
  - [POST Create a reference account for a person](/api-reference/digital-banking/account-management/#tag/Reference-accounts/paths/~1v1~1persons~1%7Bperson_id%7D~1accounts~1%7Baccount_id%7D~1reference_accounts/post)
  - [GET Index reference accounts for a person](/api-reference/digital-banking/account-management/#tag/Reference-accounts/paths/~1v1~1persons~1%7Bperson_id%7D~1accounts~1%7Baccount_id%7D~1reference_accounts/get)


#### POST Create reference account

After creating the SDD mandate, you must create a reference account resource for
the customer and link it to the internal account. You must add the customer's
`person_id` and `account_id` in the request URL. You must add the external
account details and the signed mandate information in the request body.

You must include the following properties in the request body:

- `name`: The customer's name on their external bank account.
- `iban`: The IBAN of the external bank account from which the SDD will be debited.
- `mandate_number`: The number of the SDD mandate the customer signed.
- `mandate_signature_date`: The date when the customer signed the SDD mandate.


**Request URL**


```json
// POST /v1/persons/{person_id}/accounts/{account_id}/reference_accounts
{
 	"name": "Max Mustermann",
  "iban": "DE32110101001000000029",
 	"mandate_number": "SAMPAY7D226d32882d11Eb8DcD0242Ae2F4",
 	"mandate_signature_date": "2016-04-20"
}
```

The API call returns an object with a unique ID, which is the reference account ID. The `status` field refers to the reference account's status. Possible values are `ACTIVE` and `INACTIVE`.

[Click here to view the full API reference](/api-reference/digital-banking/account-management/#tag/Reference-accounts/paths/~1v1~1persons~1%7Bperson_id%7D~1accounts~1%7Baccount_id%7D~1reference_accounts/post).

## Step 10: Create and activate decoupled card

Now that you have fully onboarded your customer, you can create a card for them. The customer can choose between different card types, such as a physical or a virtual card, with the option to tokenize the card to be used in any e-wallet, such as Google Pay, Apple Pay, or Samsung Pay. Check the [Card creation and servicing guide](/guides/cards/creation-and-servicing) for instructions on how to issue and service cards.

## Step 11: Servicing decoupled cards

This section includes information about actions customers may take after receiving their decoupled card. Customers can request the following:

* Change the reference account.
* Request a change on the credit limit available on the card.
* Disable the credit limit available on the card.
* Issue payouts to the reference account. Only in the case of having positive balance.


### Change the reference account

If the customer wants to change the reference account associated with the SDD collection, please repeat [Step 9: Create reference account and SDD mandate](#step-9-create-reference-account-and-sdd-mandate). Please be aware that you must create a new SDD mandate for the new reference account and collect the customer's signature on it.

Once you create a new reference account for the customer, the status of the previous reference account automatically changes to `INACTIVE`.

### Change the SDD collection limit

Customers can request an SDD collection limit change or disable the SDD collection limit entirely from the account. Implement the following endpoints in your solution to do so.

#### POST Create an SDD collection limit on the customer account

This endpoint creates a new SDD collection limit and attaches it to the account specified in the request URL. You must add the following properties to the request body:

* `limit`: The amount of the credit limit to be attached to the account in EURO.
* `limit_type`: The type of SDD collection limit. Use `CUSTOMER_REQUEST`.


**Request URL**


```json
// POST /persons/{person_id}/accounts/{account_id}/sdd_collection_limits
{
  "limit": {
    "value": 10000,
    "unit": "cents",
    "currency": "EUR"
  },
  "limit_type": "CUSTOMER_REQUEST"
}
```

[View POST Create SDD collection limit API reference](/api-reference/digital-banking/sepa-transfers/#tag/SDD-Collection-Limits/paths/~1v1~1persons~1%7Bperson_id%7D~1accounts~1%7Baccount_id%7D~1sdd_collection_limits/post)

#### DELETE Disable the SDD collection limit on the customer account

This endpoint disables the active SDD collection limit from the customer's account specified in the request URL. You must add the following properties to the request body:

* `limit_type`: The type of SDD collection limit. Value is `CUSTOMER_REQUEST`.


**Request URL**


```json
// DELETE /persons/{person_id}/accounts/{account_id}/sdd_collection_limits
{
  "limit_type": "CUSTOMER_REQUEST"
}
```

[View DELETE Disable SDD collection limit API reference](/api-reference/digital-banking/sepa-transfers/#tag/SDD-Collection-Limits/paths/~1v1~1persons~1%7Bperson_id%7D~1accounts~1%7Baccount_id%7D~1sdd_collection_limits/delete)

### Issue payouts to reference account

If the customer tops up the balance on the internal account associated with their decoupled card to a positive value, they can transfer the positive balance back to their reference account. To do so, implement the following endpoints in your solution:

Important
* Payouts only work if the account has a positive balance and may **only** be made to the reference account(s) associated with the decoupled card.
* Customers **cannot** transfer money from the cards's credit limit to the reference account or make a transfer to other bank accounts.


### POST Initiate a payout to a reference account

This endpoint initiates a payout to a reference account associated with a specific customer. In the request URL, you must include the customer's `account_id` (of the internal account). In the request body, you must include the following properties:

* `reference`: A field to add your unique reference for the transaction.
* `end_to_end_id`: Your unique identifier for the transaction, which will be routed throughout the whole payment process.
* `amount`: The payout amount, including `value`, `unit`, and `currency`.
* `description`: Field to add additional description for the transaction.
* `reference_account_id`: ID of the reference account to which the payout is directed. The reference account must be associated with the account specified in the request path.
* `instant_payment_rail`: The payment rail to use for an instant payout. If not specified, a regular SEPA Credit Transfer is used.


**Request URL**


```shell
POST v1/accounts/{account_id}/reference_account_payouts
```

**Response example**

The API call returns an object with a unique ID for the payout and the `status` of the payout, which can be `accepted`, `executed`, or `declined`. Once the payout is executed, a new booking will be created on the account and a `BOOKING` webhook notification will be sent.


```json
{
  "id": "12312312312pyo",
  "reference": "unique_partner_reference",
  "status": "accepted",
  "instant_payment_rail": "sepa_instant",
  "use_credit": false,
  "amount": {
    "value": 10000,
    "unit": "cents",
    "currency": "EUR",
  },
  "end_to_end_id": "123123123",
  "reference_account_id": "1231231239ref",
  "description": "Withdrawl SPAY - DD.MM.YYYY"
}
```

[View POST Initiate reference account payout API reference](/api-reference/digital-banking/transactions/#tag/Reference-account-payouts/paths/~1v1~1accounts~1%7Baccount_id%7D~1reference_account_payouts/post)

### GET Retrieve a single reference account payout

This endpoint retrieves the details of a specific payout made to a reference account. You must add the payout `id` in the request URL.

**Request URL**


```shell
GET /v1/persons/{person_id}/accounts/{account_id}/reference_account_payouts/{id}
```

[View GET Retrieve reference account payout API reference](/api-reference/digital-banking/transactions/#tag/Reference-account-payouts/paths/~1v1~1persons~1%7Bperson_id%7D~1accounts~1%7Baccount_id%7D~1reference_account_payouts~1%7Bid%7D/get)

## Appendix I: Enums

### SDD collection application status

The following table includes the possible values for the SDD collection application `status` field and their descriptions.

| Status | Description |
|  --- | --- |
| `initial_scoring_pending` | The application has been created, and the credit scoring system has been triggered to perform the initial credit checks on the customer. |
| `account_snapshot_pending` | You must create an account snapshot for the customer and attach it to the application for the final verification step required by the credit scoring system. |
| `account_snapshot_verification_pending` | The account snapshot has been attached to the application, and the credit scoring system has been triggered to perform the final verification step. |
| `rejected` | The SDD collection application has been rejected, as it did not pass the credit checks. |
| `offered` | The SDD collection application has been approved, and a limit has been offered to the customer based on the credit score. |
| `overdraft_created` | The overdraft credit limit has been created on the customer's account. |