Restricted accounts

Introduction

A restricted account is a type of account with fewer capabilities than a full Digital Banking account. The main purpose of restricted accounts is the settlement of transactions within a scope defined by you. A restricted account can be considered a "light" version of a full DiBa account.

This guide explains how to create restricted accounts for your customers and how to transfer money to and from restricted accounts.

Key characteristics of restricted accounts

  • A restricted account is always linked to a customer's reference account in their name (either a Solaris current account or an account outside of Solaris).
  • Restricted accounts can only receive incoming SEPA Credit Transfers (SCTs) (i.e., payins) from an associated reference account. The sender's name must match the name of the restricted account's account holder. Solaris automatically reviews incoming transactions to ensure that they do not exceed the transaction limit and to ensure that the names on the two accounts match. When Solaris detects a payin to a restricted account from an account for which there are no records, it will automatically associate the account as a reference account.

    • Solaris limits the amount of funds customers may pay in to their restricted accounts. The default limits are 20,000 EUR per single transaction and 200,000 EUR per month.
  • Transactions with restricted accounts may only be conducted within the scope of your solution using transfer requests, clearing transactions, or reference account payouts (depending on your use case).
  • Customers can only make payouts from their restricted accounts to their reference accounts.
  • Restricted accounts cannot be used with the following Solaris products or features:

System prerequisites

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

1. Technical setup:

Set up your environment and get your authentication keys. For step-by-step instructions, check the Technical setup guide.

2. Legal and compliance screens:

Build the necessary legal and compliance screens in your sign-up flow to collect your customers' consent to the necessary legal and compliance requirements. The Legal and compliance screens guide contains step-by-step instructions on how to create these screens and what they must contain.

Record the customer's consent on each screen as a UTC timestamp (e.g., 2019-01-01T00:00:00Z). Afterward, you must pass each timestamp in its respective field to Solaris.

  • Collect the customer's consent to Solaris's Terms and Conditions and store the timestamp in the terms_conditions_signed_at field.
  • Collect the customer's consent to data processing and store the timestamp in the data_terms_signed_at field.
  • Collect the customer's economic interest declaration and store the timestamp in the own_economic_interest_signed_at field.
  • Collect the customer's FATCA indication and store it in the fatca_relevant field. Store the timestamp in the fatca_crs_confirmed_at field.
note

The mentioned fields are part of the person resource in which all the customer data points are stored.

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.

Restricted accounts payment flow

Standard flow

This diagram shows the standard payments flow for restricted accounts:

Diagram: Restricted accounts payment flow

Step 1: Onboard customer with a restricted account

First, you must implement the standard Solaris Digital Banking customer onboarding process. Follow all of the steps in the guides listed below up to the account creation step:

note

When creating the customer's account, use one of the following account types:

  • For consumers: WALLET_PERSONAL
  • For businesses: WALLET_BUSINESS or WALLET_INSTITUTIONAL

    • Your Partner Manager will advise you on which account type to use.

Step 2: Payments to and from restricted accounts

Customers can only use the following methods to transfer money to and from their restricted accounts:

The sections below explain how to implement each method.

Receiving funds from a reference account

Customers can only top up their restricted accounts from a reference account.

To add a reference account to their restricted account, a customer must make an SCT from their reference account to the IBAN associated with their restricted account. Solaris will check to make sure that the reference account holder name matches the restricted account account holder name and that the amount of the transfer falls within the defined limits for restricted accounts. When this check passes, Solaris will automatically create a reference_account resource for the customer's reference account and associate it with the restricted account.

GET Index reference accounts

Call the following endpoint to return a list of all reference accounts associated with a specific restricted account (specified in the request URL using its unique account identifier):

Request URL:

For consumersFor businesses
Copy
Copied
GET /v1/persons/{person_id}/accounts/{account_id}/reference_accounts
Copy
Copied
GET /v1/businesses/{business_id}/accounts/{account_id}/reference_accounts

Example response:

Copy
Copied
{
    "id": "95d06bc4e448af0d78259549964e4b4bsddm",
    "status": "ACTIVE",
    "name": "Account Holder",
    "iban": "DE87110101013677175031",
    "mandate_number": "null",
    "mandate_signature_date": "null"
}

Click the links below to view the full API reference:

GET Index rejected incoming transactions

Use the following endpoint to retrieve a list of incoming transactions that Solaris rejected. Use the account ID of the restricted account in the request URL.

Request URL:

Copy
Copied
GET /v1/accounts/{account_id}/rejected_incoming_transactions

Example response:

Copy
Copied
[
  {
    "id": "95d06bc4e448af0d78259549964e4b4bsddm",
    "sender_name": "John Mustermann",
    "sender_iban": "DE32110101001000000029",
    "amount": {
      "value": 10000,
      "unit": "cents",
      "currency": "EUR"
    },
    "rejection_reason": "Transaction sender name and account debtor name do not match.",
    "rejected_at": "2022-08-18T08:36:55Z"
  }
]

Click here to view the full API reference.

Topping up their account using Card Top Ups

Customers can also use their cards to top up their restricted accounts. See the Card Top Ups guide for more information on how to implement this feature.

Sending funds to a reference account

Customers can send funds from their restricted account to a reference account using the reference account payout process.

POST Initiate payout to a reference account

This endpoint initiates a payout of funds to a customer's reference account. Note that there are separate request URLs for consumers and for businesses.

note

Customers must confirm this transaction using the change request process.

Request URL:

For consumersFor businesses
Copy
Copied
POST /v1/persons/{person_id}/accounts/{account_id}/reference_accounts/{reference_account_id}/payouts
Copy
Copied
POST /v1/businesses/{business_id}/accounts/{account_id}/reference_accounts/{reference_account_id}/payouts

Example request:

Copy
Copied
{
  "reference": "payout_unique_ref",
  "end_to_end_id": "end_to_end_id",
  "description": "Withdrawal SPAY - DD.MM.YYYY",
  "amount": {
    "value": 100,
    "currency": "EUR",
    "unit": "cents"
  }
}

Example response (after confirming the change request):

Copy
Copied
{
  "id": "4b157d71def54b5c9dac28ef1d04432c",
  "reference": "9d2b59c2-c68f-413c-b2a9-a2f5bfd3f669",
  "status": "ACCEPTED",
  "end_to_end_id": "end_to_end_ref",
  "description": "Payout description",
  "reference_account_id": "78f354e508314bb8ac982a3d7f969dde"
}

Click the links below to read the full API reference:

GET Index reference account payouts

This endpoint returns an array containing all reference account payouts from the Solaris account specified in the request URL. Note that there are separate URLs for consumer accounts and business accounts.

Request URL:

For consumersFor businesses
Copy
Copied
GET /v1/persons/{person_id}/accounts/{account_id}/reference_account_payouts
Copy
Copied
GET /v1/businesses/{business_id}/accounts/{account_id}/reference_account_payouts

Example response:

Copy
Copied
[
  {
    "id": "4b157d71def54b5c9dac28ef1d04432c",
    "reference": "9d2b59c2-c68f-413c-b2a9-a2f5bfd3f669",
    "status": "ACCEPTED",
    "end_to_end_id": "end_to_end_ref",
    "description": "Payout description",
    "reference_account_id": "78f354e508314bb8ac982a3d7f969dde"
  }
]

Click the links below to view the full API reference:

GET Retrieve reference account payout

This endpoint returns a single reference account payout. Specify the ID of the payout to return in the request URL. Note that there are separate URLs for consumers and businesses.

Request URL:

For consumersFor businesses
Copy
Copied
GET /v1/persons/{person_id}/accounts/{account_id}/reference_account_payouts/{id}
Copy
Copied
GET /v1/businesses/{business_id}/accounts/{account_id}/reference_account_payouts/{id}

Example response:

Copy
Copied
{
  "id": "4b157d71def54b5c9dac28ef1d04432c",
  "reference": "9d2b59c2-c68f-413c-b2a9-a2f5bfd3f669",
  "status": "ACCEPTED",
  "end_to_end_id": "end_to_end_ref",
  "description": "Payout description",
  "reference_account_id": "78f354e508314bb8ac982a3d7f969dde"
}

Click the links below to view the full API reference:

Transferring funds to another restricted account

Customers can transfer funds between restricted accounts that they own using the transfer request process. This process consists of two steps:

  1. Call the POST Create transfer request endpoint. This will create a reservation on the restricted account for a given amount.
  2. Call the POST Execute transfer request endpoint to send a sum less than or equal to the reservation amount to the designated recipient. You can either send the entire amount of the reservation in one execution or split it up over multiple executions.

POST Create transfer request

This endpoint creates a transfer request for the account specified in the request URL. Solaris will create a reservation on the account for the amount of the transfer request.

Request URL:

Copy
Copied
POST /v1/accounts/{account_id}/transfer_requests

Example request:

Copy
Copied
{
  "amount": {
    "value": 10000,
    "unit": "cents",
    "currency": "EUR"
  },
  "reference": "e8eabf80-095f-4d6a-947a-4ca1455cc378",
  "description": "An example description"
}

Example response:

Copy
Copied
{
  "id": "d3441a66f78e6290cdeebc4c1689a4aetreq",
  "reservation_id": "88cedf447b2c43828ded233733d1cc54",
  "amount": {
    "amount": 1000,
    "unit": "cents",
    "currency": "EUR"
  },
  "reference": "e8eabf80-095f-4d6a-947a-4ca1455cc378",
  "description": "Example description",
  "resolved": false
}

Click here to view the full API reference.

POST Execute transfer request

This API call executes the transfer request specified in the request URL.

Note that you can execute a transfer request for less than or equal to the transfer request amount. In case the amount is lower, a new reservation of the remaining amount will be created and the associated reservation_id of the transfer request will be updated. You must then release the previous reservation using PATCH Resolve a transfer request.

Request URL:

Copy
Copied
POST /v1/accounts/{id}/transfer_requests/{id}/executions

Example request:

Copy
Copied
{
  "amount": {
    "value": 10000,
    "currency": "EUR"
  },
  "reference": "a95f2aaf-4e0c-4d49-8021-8a16a884ed86",
  "description": "Wallet-to-wallet payment",
  "recipient_iban": "DE32110101001000000029",
  "end_to_end_id": "426d61f5-8fa2-443d-ab0a-7245b06d46a7",
  "type": "CRYPTO_EXCHANGE"
}

Example response:

Copy
Copied
{
  "id": "e451ce22c8b1438d8befe2a29182fc83",
  "amount": {
    "value": 0,
    "unit": "string",
    "currency": "EUR"
  },
  "status": "OPEN",
  "type": "CRYPTO_EXCHANGE",
  "recipient_iban": "DE32110101001000000029",
  "instruction_id": "GT5VCLgQCkpcyTCnHuXdg8nSVz2hjDpY4Qw",
  "reference": "55207045-4509-4278-9f44-0947635f4d75",
  "description": "Example description"
}

Click here to view the full API reference.

GET Index transfer requests for an account

This endpoint returns an array containing all transfer requests associated with an account.

You can use the following filters with this request:

  • filter[reference]
  • filter[resolved]
  • filter[reservation_id]

All entries are sorted in descending order.

Request URL:

Copy
Copied
GET /v1/accounts/{id}/transfer_requests

Example response:

Copy
Copied
[
  {
    "id": "d3441a66f78e6290cdeebc4c1689a4aetreq",
    "reservation_id": "88cedf447b2c43828ded233733d1cc54",
    "amount": {
      "amount": 1000,
      "unit": "cents",
      "currency": "EUR"
    },
    "reference": "e8eabf80-095f-4d6a-947a-4ca1455cc378",
    "description": "Example description",
    "resolved": false
  }
]

Click here to view the full API reference.

GET Index transfer request executions

This endpoint retrieves an array containing all executions of a transfer request. Supply the ID of the transfer request in the request URL.

Request:

Copy
Copied
GET /v1/accounts/{id}/transfer_requests/{id}/executions

Response:

Copy
Copied
[
  {
    "id": "e451ce22c8b1438d8befe2a29182fc83",
    "amount": {
      "value": 0,
      "unit": "string",
      "currency": "EUR"
    },
    "status": "OPEN",
    "type": "CRYPTO_EXCHANGE",
    "recipient_iban": "DE32110101001000000029",
    "instruction_id": "GT5VCLgQCkpcyTCnHuXdg8nSVz2hjDpY4Qw",
    "reference": "55207045-4509-4278-9f44-0947635f4d75",
    "description": "Example description"
  }
]

Click here to view the full API reference.

PATCH Resolve a transfer request

This endpoint resolves a reservation created by a transfer request. All reserved funds will be released to the account. You can use this endpoint on transfer requests regardless of whether or not they have already been executed.

Request URL:

Copy
Copied
PATCH /v1/accounts/{id}/transfer_request/{id}/resolve

Example response:

Copy
Copied
{
  "id": "d3441a66f78e6290cdeebc4c1689a4aetreq",
  "reservation_id": "88cedf447b2c43828ded233733d1cc54",
  "amount": {
    "amount": 1000,
    "unit": "cents",
    "currency": "EUR"
  },
  "reference": "e8eabf80-095f-4d6a-947a-4ca1455cc378",
  "description": "Example description",
  "resolved": false
}

Click here to view the full API reference.

Step 3: Restricted accounts servicing

You can service restricted accounts the same way you would service a regular Solaris account. See the Account management guide for more information on how to do so.

Step 4: Statements of Account for restricted accounts

You are required to provide your customers with a history of the transactions and their restricted account balance in the form of a statement of account.

See the account management guide for information on how to implement these endpoints in your solution.