# Restricted Accounts

A **Restricted Account** is a limited-capability current account designed primarily for settlement transactions within a defined scope (e.g., a Crypto wallet or Investment account).

Unlike a full Digital Banking account, a restricted account operates in a "closed loop" with a linked **Reference Account**.

## Key characteristics

* **Closed Loop:** Funds can typically only enter from or exit to a linked **Reference Account** (an external bank account held in the customer's name).
* **Auto-Linking:** When a customer sends an SCT (SEPA Credit Transfer) to their Restricted Account for the first time, Solaris validates the sender's name. If it matches, that external account is automatically saved as a **Reference Account**.
* **Limits:** Default pay-in limits are **20,000 EUR** per transaction and **200,000 EUR** per month.
* **Excluded Features:** Restricted accounts **cannot** support:
  * [Debit Cards](/guides/cards)
  * [Overdrafts](/guides/lending/overdrafts)
  * [SEPA Direct Debits (Outgoing)](/guides/digital-banking/sepa-transfers/sepa-direct-debit-transfer)
  * [Sub-accounts](/guides/digital-banking/sub-accounts)


## System prerequisites

Before starting the customer onboarding process, you must implement the following requirements:

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

## Webhooks

Subscribe to these events to track account status and transactions:

Solaris recommends subscribing to the following webhook events to automate your wallet and compliance processes.

### Account & Transaction Events

Track the lifecycle of the account and incoming/outgoing funds.

- [`ACCOUNT_BLOCK`](/api-reference/onboarding/webhooks/webhook-events/paths/account_block/post)
- [`ACCOUNT_CLOSURE_REQUEST`](/api-reference/onboarding/webhooks/webhook-events/paths/account_closure/post)
- [`ACCOUNT_CLOSURE`](/api-reference/onboarding/webhooks/webhook-events/paths/account_closure/post)
- [`BOOKING`](/api-reference/onboarding/webhooks/webhook-events/paths/booking/post) - **Critical.** A transaction (incoming or outgoing) was booked.
- [`INCOMING_REJECTED_TRANSACTION`](/api-reference/onboarding/webhooks/webhook-events/paths/incoming_rejected_transaction/post)
- [`REFERENCE_ACCOUNT_CREATED`](/api-reference/onboarding/webhooks/webhook-events/paths/reference_account_created/post)


### Customer Data (Person)

Monitor changes to retail customer data.

- [`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_TAX_IDENTIFICATION_CHANGED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_tax_identification_changed/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)
- [`IDENTIFICATION`](/api-reference/onboarding/webhooks/webhook-events/paths/identification/post)


### Customer Data (Business)

Monitor changes to business entities and their representatives.

- [`BUSINESS_CHANGED`](/api-reference/onboarding/webhooks/webhook-events/paths/business_changed/post)
- [`BUSINESS_DELETED`](/api-reference/onboarding/webhooks/webhook-events/paths/business_deleted/post)
- [`BUSINESS_IDENTIFICATION`](/api-reference/onboarding/webhooks/webhook-events/paths/business_identification/post)
- [`BUSINESS_TAX_IDENTIFICATION_CHANGED`](/api-reference/onboarding/webhooks/webhook-events/paths/business_tax_identification_changed/post)
- [`BENEFICIAL_OWNER`](/api-reference/onboarding/webhooks/webhook-events/paths/beneficial_owner/post)
- [`LEGAL_REPRESENTATIVE`](/api-reference/onboarding/webhooks/webhook-events/paths/legal_representative/post)


### Seizures (Garnishments)

Notifications when authorities seize funds or update seizure status.

**Person Seizures:**

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


**Business Seizures:**

- [`BUSINESS_SEIZURE_CREATED`](/api-reference/onboarding/webhooks/webhook-events/paths/business_seizure_created/post)
- [`BUSINESS_SEIZURE_UPDATED`](/api-reference/onboarding/webhooks/webhook-events/paths/business_seizure_updated/post)
- [`BUSINESS_SEIZURE_FULFILLED`](/api-reference/onboarding/webhooks/webhook-events/paths/business_seizure_fulfilled/post)
- [`BUSINESS_SEIZURE_DELETED`](/api-reference/onboarding/webhooks/webhook-events/paths/business_seizure_deleted/post)


### Security & Communication

- [`POSTBOX_ITEM_CREATED`](/api-reference/onboarding/webhooks/webhook-events/paths/postbox_item_created/post)


[View all Webhooks](/api-reference/onboarding/webhooks/)

## Payment flow overview

Restricted accounts rely on a specific flow of funds between the Customer, the Partner (you), and the Reference Account.

Diagram: Restricted Accounts Payment Ecosystem
## 1. Onboard the customer

Follow the standard **Account Opening** process, but use the specific ledger types for restricted accounts.

1. **Identify:** Complete the [Onboarding](/guides/get-started/digital-banking/onboard-person) process.
2. **Create:** Submit an [Account Opening Request (AOR)](/guides/digital-banking/account-opening) with the specific parameters below.


Configuration
When calling the AOR endpoint, you **must** use one of the following `account_type` values (instead of `CHECKING_...`):

* **Consumers:** `WALLET_PERSONAL`
* **Businesses:** `WALLET_BUSINESS` or `WALLET_INSTITUTIONAL`


Contact your Partner Manager to confirm which type applies to your product.

## 2. Funding the account (Pay-in)

There are two ways to fund a restricted account.

### Method A: SEPA Transfer (SCT)

The customer sends a standard bank transfer from their external bank account to the Restricted Account's IBAN.

**The Auto-Link Logic:**

1. **Receipt:** Solaris receives the incoming SCT.
2. **Validation:** Solaris compares the **Sender Name** (from the SCT) with the **Account Holder Name** (on the Restricted Account).
3. **Outcome:**
  * **Match:** The funds are credited, and the sender's IBAN is automatically stored as a verified **Reference Account**.
  * **Mismatch:** The transaction is rejected and returned.


### Method B: Card Top-Ups

Customers can instantly fund their restricted account using a debit or credit card (or Apple/Google Pay). This is faster than SEPA and improves conversion.

Instant Top-Ups Guide
Learn how to integrate the Stripe + Solaris Top-Up flow.

### Manage reference accounts & pay-ins

**List Reference Accounts**
Retrieve all external accounts linked to this restricted account.


```shell
GET /v1/persons/{person_id}/accounts/{account_id}/reference_accounts
```

**Check Rejected Pay-ins**
If a customer claims they sent funds that never arrived, check the rejection log (usually due to a name mismatch).


```shell
GET /v1/accounts/{account_id}/rejected_incoming_transactions
```

List Reference Accounts
View endpoint.

Rejected Transactions
View endpoint.

## 3. Payouts (Reference Account)

Customers can withdraw funds *only* to a verified Reference Account.

**Prerequisite:** The transaction requires [Change Request](/guides/authentication/strong-customer-authentication#change-request) authorization (SCA).

### Initiate payout

Call this endpoint to create the payout request.

**SCA Flow:** The API returns `202 Accepted` with a `change_request_id`. You must use this ID to complete the [Change Request](/guides/authentication/strong-customer-authentication#change-request) process. Once confirmed, the payout executes.


```json
// POST /v1/accounts/{account_id}/reference_account_payouts
{
  "reference_account_id": "d5325027ca2840d4b3a97b8ec8b837f0racc",
  "amount": { "value": 100, "currency": "EUR", "unit": "cents" },
  "description": "Withdrawal to main bank",
  "reference": "unique_payout_ref_123" // Idempotency key
}
```

**Response (202 Accepted):**


```json
{
  "id": "d6c778822b2d7bd3b778935bcfd02d1d3csc", // Use this Change Request ID
  "status": "AUTHORIZATION_REQUIRED",
  "url": "[https://api.solaris-sandbox.de/v1/change_requests/.../authorize](https://api.solaris-sandbox.de/v1/change_requests/.../authorize)"
}
```

### Retrieve payouts

You can list all payouts or retrieve a specific one by ID.

List All

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

Retrieve Single

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

**Response:**


```json
{
  "id": "4b157d71def54b5c9dac28ef1d04432c",
  "status": "ACCEPTED",
  "amount": { "currency": "EUR", "value": 100 },
  "reference_account_id": "78f354e508314bb8ac982a3d7f969dde"
}
```

Reference Payouts API
View full technical reference.

## 4. Internal transfers (Transfer Request)

Customers can transfer funds between two restricted accounts they own (e.g., moving funds from a "Euro Wallet" to a "Crypto Settlement Wallet") using the **Transfer Request** process.

This is a 3-step process designed for transactional safety:

1. **Reserve:** Block the funds.
2. **Execute:** Move the funds (partial or full).
3. **Resolve:** Release any remaining reservation.


### Step A: Create request (Reservation)

This creates a **Reservation** on the account. The funds are blocked but not moved.


```json
// POST /v1/accounts/{account_id}/transfer_requests
{
  "amount": { "value": 10000, "currency": "EUR" },
  "description": "Reservation for Crypto Buy",
  "reference": "unique_ref_123" // Idempotency key
}
```

**Returns:** `reservation_id` and `id` (the transfer request ID).

### Step B: Execute request

Move the funds to the target recipient. You can execute **less** than the reserved amount.


```json
// POST /v1/accounts/{account_id}/transfer_requests/{transfer_request_id}/executions
{
  "amount": { "value": 10000, "currency": "EUR" }, // Can be <= reserved amount
  "recipient_iban": "DE32110101001000000029",
  "type": "CRYPTO_EXCHANGE", // Enum: CRYPTO_EXCHANGE or PARTNER_FEE
  "reference": "unique_exec_ref_123"
}
```

### Step C: Resolve request

If you executed *less* than the reserved amount (or canceled the operation), you **must** call this endpoint to release the remaining blocked funds.


```shell
PATCH /v1/accounts/{account_id}/transfer_requests/{transfer_request_id}/resolve
```

### Monitor transfer requests

Track the status of reservations and executions.

List Requests
Returns all transfer requests (Reservations) for an account.


```shell
GET /v1/accounts/{account_id}/transfer_requests?filter[resolved]=false
```

List Executions
Returns all executions (actual movements) for a specific request.


```shell
GET /v1/accounts/{account_id}/transfer_requests/{transfer_request_id}/executions
```

**Response:**


```json
[
  {
    "id": "e451ce22c8b1438d8befe2a29182fc83",
    "amount": { "value": 10000, "currency": "EUR" },
    "status": "EXECUTED",
    "type": "CRYPTO_EXCHANGE"
  }
]
```

Transfer Requests API
View endpoints for reservations and executions.

## Service & Reporting

### Statements of Account

Restricted accounts require standard reporting. You must provide customers with a **Statement of Account** (SoA).
See the [Account Management](/guides/digital-banking/account-management#statements-of-account) guide for implementation details.