Account management

This page contains information about the primary components of an account, how to manage your customer's accounts, and what sorts of information you can query about the account using Solaris' API.

Prerequisites

You may only create customer accounts once your customers have gone through Solaris' onboarding process. See the Get started guide to learn about all of the necessary steps you must implement before you can create a customer account.

Account servicing

All of the major operations related to servicing accounts—e.g., creating an account, updating an account—are governed by the account management API endpoints.

Some operations are organized by the account resource that they control, while others are organized according to the type of customer (i.e., person vs. business).

Person accounts:

• Retrieve an account
• Index all accounts for a customer
• Update an account

Business accounts:

• Retrieve an account
• Index all accounts for a business

Account balance

The account balance represents the amount of funds available on the account. The Solaris API does not expose the account balance as a single value or object, but rather through a set of different balance types. The next section describes these types in detail.

The following elements factor in to the calculation of the account balance:

• Bookings: A booking represents the movement of funds on an account. Bookings are created for SEPA Credit Transfers (SCTs) and SEPA Direct Debits (SDDs). See the bookings section for more details.
• Reservations: A reservation represents funds that are temporarily blocked on an account, e.g., during the time required to process an accepted payment or until the corresponding booking is posted on the account. Reservations are created for card transactions only. See the reservations section for more details.
• Dispositions: A disposition is a pending booking with a valuta_date in the future. While the API will return them along with the other bookings, dispositions have not yet been applied to the account balance.
• Account limits: The account limit determines the maximum allowed negative account balance.

Balance types

The API expresses an account's balance using the following objects:

• balance: Shows the amount of funds that a customer currently has on their account. This object only includes posted bookings (i.e., bookings with an elapsed valuta_date).
• available_balance: Shows the amount of funds that a customer currently has on their account minus any funds that are held in reservations (i.e., the amount of money the customer currently has at their disposal).
• Period balance (balance_start and balance_end): Statements of account and bank statements display the balances at the beginning and at the end of their respective statement periods. The balance_start is calculated based on bookings with a booking_date after (i.e., excluding) the statement start date. The balance_end is calculated based on bookings with a booking_date up to or on (i.e., including) the statement end date.
• seizure_protection: Describes the current Seizure Protection state of the account. It includes the amount of funds on the account that have been blocked by a seizure and the amount that is seizure-protected. This object is only returned for seizure-protected accounts. See the seizure protection documentation for more information.

Example: Balance calculation

Consider an account with the following bookings over a three-month period:

Here is an example of how the different balances would be calculated based on these bookings (assuming an account limit of 100,00):

Account balance API endpoints

See the following API references for endpoints related to account balances:

• GET Retrieve balance for an account
• GET Retrieve the average daily balance for an account

Bookings

A booking represents the movement of funds on an account. When Solaris' system executes payment instructions or receives a payment, it places a booking on the relevant customer's account. Bookings contain important information about the payment instruction and factor in to the calculation of the account balance.

The Solaris API represents bookings as objects. The information contained in a booking object depends on the type of transaction that it represents. A SEPA Direct Debit (SDD) booking will, for instance, contain information about the SEPA Direct Debit mandate, while a SEPA Credit Transfer booking will not have this information.

The booking object includes the transaction_id property, which exposes the ID of the original transaction that led to the booking. For R-Transactions (i.e., payments rejected by the receiving bank or the clearing house), the resulting booking will use the return_transaction_id attribute to expose the ID of the original (returned) transaction.

For a full list of booking types, see the appendix below.

GET Retrieve all bookings for an account

Click here to view the API reference for GET Retrieve bookings for an account.

Reservations

A reservation is a temporary restriction of a set of funds on an account. These funds are reserved as a deposit for a payment operation that has already occurred or will occur in the future. Solaris uses reservations to calculate a customer's available balance (i.e., the funds on the account that the customer can use at that moment) and to check whether or not the balance is high enough to cover a payment.

Reservation lifecycle

Reservations resolve in one of two ways:

• Resolution based on an event: For example, when Solaris reserves funds after a customer makes a card transaction, then the reservation will resolve as soon as the related credit transfer has successfully executed. Once this happens, a booking for the transaction amount will appear on the customer's account.
• Expiration: In the unlikely event that a reservation does not get resolved, it will automatically upon reaching the default expiry date.

Reservations API endpoints

See the following API references for endpoints related to reservations:

• GET Index reservations for an account

Statements of account

According to § 355 HGB, banks are legally required to regularly issue a statement of account (Rechnungsabschluss) that contains information about all bookings, interest, fees, and costs.

The statement of account contains an important legal disclaimer:

• English
• German

The statement of account also includes general information about the account itself, such as its IBAN and the account owner's details. It serves as the basis for all potential claims against the customer for the settlement of a credit balance.

If your solution includes Overdrafts, then the statement of account will include the following info:

• overdraft_facility: Overdraft facility that has been granted to the customer.
• overdraft_rate: The increased interest rate applied when going below the granted overdraft facility.
• interest_accrual_rate: The daily rate at which interest is accrued on the used amount of an overdraft.
• interest_accrued: The interest accrued, in Euro cents.

How to generate a statement of account

According to the Solaris Terms and Conditions, Solaris provides this document through your solution to customers:

• individually on a quarterly basis, or
• combined as a single document with the bank statement (Kontoauszug) with the entirety of the information contained in both, including the legal disclaimer.

First, you must call the POST Create statement of account endpoint. The API will respond with all of the information you need to include in the statement of account that you provide to your customer:

{
  "id": "e349cdc6b712035236bed32d7399ab72csoa",
  "year": 2022,
  "interval": "MONTHLY",
  "period": 3,
  "statement_number": "2022-M-03",
  "recipient_information": {
    "line_1": "Mr. Peter Mustermann",
    "line_2": "Musterstrasse 23",
    "line_3": "10409 Berlin",
    "line_4": "DE",
    "line_5": "string",
    "line_6": "string"
  },
  "issue_date": "2022-04-01",
  "statement_period_start_date": "2022-03-01",
  "statement_period_end_date": "2022-03-31",
  "overdraft_facility": {
    "value": 10000,
    "unit": "cents",
    "currency": "EUR"
  },
  "interest_accrual_rate": 12.5,
  "overdraft_rate": 9,
  "interest_accrued": {
    "value": 10000,
    "unit": "cents",
    "currency": "EUR"
  },
  "account_information": {
    "account": {
      "iban": "DE76110101001100000999",
      "bic": "SOBKDEBBXXX"
    },
    "balance_start": {
      "value": 20321,
      "unit": "cents",
      "currency": "EUR"
    },
    "balance_end": {
      "value": 18405,
      "unit": "cents",
      "currency": "EUR"
    }
  },
  "disclaimer": "Sehr geehrte Kundin, sehr geehrter Kunde,\\nbitte prüfen Sie die Buchungen, Berechnungen und den Abschlusssaldo im beiliegenden Kontoauszug, der zugleich einen Rechnungsabschluss darstellt. Rechnungsabschlüsse gelten als genehmigt, sofern Sie innerhalb von sechs Wochen nach Zugang keine Einwendungen erheben. Einwendungen gegen Rechnungsabschlüsse müssen der solarisBank schriftlich oder in Textform (z.B. an support@solarisgroup.com) zugehen. Im Falle der Einwendung in Textform genügt zur Fristwahrung die rechtzeitige Absendung. Der angegebene Kontostand berücksichtigt nicht die Wertstellung der einzelnen Buchungen. Dies bedeutet, dass der genannte Betrag nicht dem für die Zinsrechnung maßgeblichen Kontostand entsprechen muss und bei Verfügungen möglicherweise Zinsen für die Inanspruchnahme einer eingeräumten oder geduldeten Kontoüberziehung anfallen können. Gutschriften aus eingereichten Lastschriften und anderen Einzugspapieren erfolgen unter dem Vorbehalt der Einlösung. Guthaben sind als Einlagen nach Maßgabe des Einlagensicherungsgesetzes entschädigungsfähig. Nähere Informationen können dem Informationsbogen für den Einleger entnommen werden, den Sie gemeinsam mit unseren für den Geschäftsverkehr mit Ihnen geltenden Allgemeinen Geschäftsbedingungen und besonderen Bedingungen unter www.solarisbank.de/partner einsehen können.\\nMit freundlichen Grüßen\\nIhre solarisBank"
}

Use the data from the response to generate your own branded .pdf file to provide to the customer.

Recipient data structure

The recipient_information property contains up to six lines of information about the recipient, each stored in its own property. The values of these properties will differ based on whether the recipient is a person or a business. See the table below for information on how the values are populated for persons vs. businesses:

Bank statements

A bank statement (Kontoauszug) displays all money movements (i.e., bookings) posted to the account during a specific time span. Bank statements include general information about the account and its owner, a start and end date, and all bookings with a booking_date that falls between these dates.

According to Article 248 §§ 3, 7,10 EGBGB, banks are legally required to provide information about every booking to the customer at least once a month in .pdf format. The bank statement displays the following information for each booking:

• Reference number and purpose of the payment
• The amount of the payment
• Fees and interest (if applicable)
• Exchange rate (if applicable)
• Value date or entry date

How to generate a bank statement

Call the POST Create a bank statement endpoint. The API will return all of the information for the bank statement in JSON format:

{
  "id": "4463f72f46cc9233c5494146f01b152ccsas",
  "recipient_information": {
    "line_1": "Mr. Peter Mustermann",
    "line_2": "Musterstrasse 23",
    "line_3": "10409 Berlin",
    "line_4": "DE",
    "line_5": "string",
    "line_6": "string"
  },
  "issue_date": "2022-04-01",
  "statement_period_start_date": "2022-03-01",
  "statement_period_end_date": "2022-03-31",
  "overdraft_facility": {
    "value": 10000,
    "unit": "cents",
    "currency": "EUR"
  },
  "account_information": {
    "account": {
      "iban": "DE76110101001100000999",
      "bic": "SOBKDEBBXXX"
    },
    "balance_start": {
      "value": 20321,
      "unit": "cents",
      "currency": "EUR"
    },
    "balance_end": {
      "value": 18405,
      "unit": "cents",
      "currency": "EUR"
    }
  },
  "disclaimer": "Sehr geehrte Kundin, sehr geehrter Kunde,\\nbitte prüfen Sie die Buchungen, Berechnungen und den Abschlusssaldo im beiliegenden Kontoauszug, der zugleich einen Rechnungsabschluss darstellt. Rechnungsabschlüsse gelten als genehmigt, sofern Sie innerhalb von sechs Wochen nach Zugang keine Einwendungen erheben. Einwendungen gegen Rechnungsabschlüsse müssen der solarisBank schriftlich oder in Textform (z.B. an support@solarisbank.de) zugehen. Im Falle der Einwendung in Textform genügt zur Fristwahrung die rechtzeitige Absendung. Der angegebene Kontostand berücksichtigt nicht die Wertstellung der einzelnen Buchungen. Dies bedeutet, dass der genannte Betrag nicht dem für die Zinsrechnung maßgeblichen Kontostand entsprechen muss und bei Verfügungen möglicherweise Zinsen für die Inanspruchnahme einer eingeräumten oder geduldeten Kontoüberziehung anfallen können. Gutschriften aus eingereichten Lastschriften und anderen Einzugspapieren erfolgen unter dem Vorbehalt der Einlösung. Guthaben sind als Einlagen nach Maßgabe des Einlagensicherungsgesetzes entschädigungsfähig. Nähere Informationen können dem Informationsbogen für den Einleger entnommen werden, den Sie gemeinsam mit unseren für den Geschäftsverkehr mit Ihnen geltenden Allgemeinen Geschäftsbedingungen und besonderen Bedingungen unter www.solarisbank.de/partner einsehen können.\\nMit freundlichen Grüßen\\nIhre solarisBank"
}

You may then use this information to generate a branded .pdf file for your customer.

Appendix I: Booking types

Appendix II: Reservation types

Possible values for reservation_type are:

• CARD_AUTHORIZATION: Used when a customer makes a card transaction.
• SEIZURE: Used when a seizure is placed on a customer's account to collect funds.

Appendix III: Account blocking

Solaris could block customers' accounts for different reasons. Account blocks also have different levels. For example, an account could have a credit, debit, or full block.

You can monitor account blocks for your customers' accounts by subscribing to the webhook event ACCOUNT_BLOCK. If a customer's account is blocked, you'll receive a notification from this webhook event, and the payload will include the locking_status.

Afterward, you can call GET Retrieve an account to get the locking_reason.

The locking_status indicates the block level on the account (full, credit, or debit), whereas the locking_reason field includes the reason Solaris has blocked the customer's account.

Account locking status

The locking_status field shows the account's status and whether or not there's a block on the account. The following table includes the possible values for the field and their descriptions:

Account locking reasons

The locking_reasons field includes the reason why the account was blocked. The following table includes the possible values for the field and their descriptions: