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:

  • Debit cards
  • Overdrafts
  • SEPA Direct Debit
  • Sub-accounts

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.

The following screens are required to onboard B2C and freelancer customers for Digital Banking & Cards:

1. Terms and Conditions
2. Customer information
3. Economic interest
4. Person tax information (Only for customers in Germany)
5. FATCA indication
6. Self-declaration as a politically exposed person (PEP). (Only for customers in France, Italy, and Spain)
7. Compliance screen

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.

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.

• ACCOUNT_BLOCK
• ACCOUNT_CLOSURE_REQUEST
• ACCOUNT_CLOSURE
• BENEFICIAL_OWNER
• BOOKING
• BUSINESS_CHANGED
• BUSINESS_DELETED
• BUSINESS_SEIZURE_CREATED
• BUSINESS_SEIZURE_DELETED
• BUSINESS_SEIZURE_FULFILLED
• BUSINESS_SEIZURE_UPDATED
• BUSINESS_IDENTIFICATION
• BUSINESS_TAX_IDENTIFICATION_CHANGED
• IDENTIFICATION
• INCOMING_REJECTED_TRANSACTION
• LEGAL_REPRESENTATIVE
• PERSON_CHANGED
• PERSON_DELETED
• PERSON_SEIZURE_CREATED
• PERSON_SEIZURE_DELETED
• PERSON_SEIZURE_FULFILLED
• PERSON_SEIZURE_UPDATED
• PERSON_MOBILE_NUMBER_CREATED
• PERSON_MOBILE_NUMBER_DELETED
• PERSON_TAX_IDENTIFICATION_CHANGED
• POSTBOX_ITEM_CREATED
• REFERENCE_ACCOUNT_CREATED
• SCA_CHALLENGE

Restricted accounts payment flow

Standard flow

This diagram shows the standard payments flow for restricted accounts:

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:

• For consumers: Onboard a person
• For businesses: Onboard a business

Step 2: Payments to and from restricted accounts

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

• Receiving funds from a reference account
• Topping up their account using Card Top Ups
• Sending funds to a reference account
• Transferring funds to another restricted account

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:

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

GET /v1/businesses/{business_id}/accounts/{account_id}/reference_accounts

Example response:

{
    "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 reference accounts for a person
• GET Index reference accounts for a business

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:

GET /v1/accounts/{account_id}/rejected_incoming_transactions

Example response:

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

Request URL:

POST /v1/persons/{person_id}/accounts/{account_id}/reference_accounts/{reference_account_id}/payouts

POST /v1/businesses/{business_id}/accounts/{account_id}/reference_accounts/{reference_account_id}/payouts

Example request:

{
  "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):

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

• POST Initiate payout to a person's reference account
• POST Initiate payout to a business' reference account

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:

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

GET /v1/businesses/{business_id}/accounts/{account_id}/reference_account_payouts

Example response:

[
  {
    "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 Index payouts to a person's reference account
• GET Index payouts to a business' reference account

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:

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

GET /v1/businesses/{business_id}/accounts/{account_id}/reference_account_payouts/{id}

Example response:

{
  "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 a payout to a person's reference account
• GET Retrieve a payout to a business' reference account

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:

POST /v1/accounts/{account_id}/transfer_requests

Example request:

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

Example response:

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

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

Example request:

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

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

GET /v1/accounts/{id}/transfer_requests

Example response:

[
  {
    "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:

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

Response:

[
  {
    "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:

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

Example response:

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