Skip to content
/
Restricted accounts
Last updated

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:

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

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 TypeAPI Field (Person Resource)
Terms & Conditionsterms_conditions_signed_at
Data Processingdata_terms_signed_at
Economic Interestown_economic_interest_signed_at
FATCA/CRSfatca_crs_confirmed_at

View the Legal Screens Guide

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.

Customer Data (Person)

Monitor changes to retail customer data.

Customer Data (Business)

Monitor changes to business entities and their representatives.

Seizures (Garnishments)

Notifications when authorities seize funds or update seizure status.

Person Seizures:

Business Seizures:

Security & Communication

View all 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 process.
  2. Create: Submit an Account Opening Request (AOR) 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.

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

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 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 process. Once confirmed, the payout executes.

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

{
  "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.

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

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.

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

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

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

Monitor transfer requests

Track the status of reservations and executions.

Returns all transfer requests (Reservations) for an account.

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

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 guide for implementation details.

Previous page
Next page