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

note

See the account closure guide for information about closing a customer's account.

Person accounts:

Business accounts:

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:

Booking dateValuta dateBooking typeAmount
2021-12-312022-01-01SEPA_CREDIT_TRANSFER10,00
2022-01-012021-12-31INTEREST_ACCRUED-5,00
2022-02-012022-02-01SEPA_CREDIT_TRANSFER-5,00
2022-03-012022-03-01SEPA_CREDIT_TRANSFER20,00
2022-03-012022-03-02SEPA_CREDIT_TRANSFER7,00
2022-03-022022-03-02SEPA_DIRECT_DEBIT12,00
2022-03-042022-03-04SEPA_CREDIT_TRANSFER-6,00

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

BalanceDateValueComment
balance2022-03-0120,00Current funds on the account on this date. The account limit is not included in the calculation.
available balance2022-03-01114,00The funds available to the customer on this date. The positive booking of 12,00 on 2022-03-02 is not included in the calculation. The negative booking of -6,00 on 2022-03-04 and the account limit are included.
balance_start2022-01-01 (statement period start date)10,00The funds on the account on this date. This value is calculated based on bookings with a booking date before the given date.
balance_end2022-03-01 (statement period end date)27,00The funds on the account on this date. This value is calculated based on bookings with a booking date up to and including the given date.

Account balance API endpoints

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

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.

Note
  • Design your solution to fully utilize and expose the information contained in a booking object, both in your frontend and in your statements of account and bank statements.
  • Do not ignore bookings with less-common or unexpected booking types. Solaris will occasionally add new booking types to the API, and your solution should always be able to handle them. Do not rely solely on the list of booking types provided below.

Bookings API endpoints

Click here to view the API reference for booking-related endpoints.

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.

note

Solaris only creates reservations for card transactions. For other types of transactions, Solaris creates bookings.

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:

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:

Clearance of account is considered accepted if you do not raise any objection within six weeks after receipt. Objections regarding account statements have to be submitted to solarisBank in written or text form (e.g. to service@solarisbank.de). In case of objection in text form, it is sufficient to ensure its timely dispatch.

Sehr geehrte Kundin, sehr geehrter Kunde,

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

Mit freundlichen Grüßen

Ihre solarisBank

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.

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:

Copy
Copied
{
    "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",
    "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"
}

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

Note

The generated .pdf file must contain all of the information returned by this endpoint, including the legal disclaimer.

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:

LineNatural personBusiness
First lineSalutation, first name, last nameCompany name
Second lineFirst address line"For the company management"
Third lineSecond address lineFirst address line
Forth linePostal code, city nameSecond address line
Fifth lineCountry namePostal code, city name
Sixth line-Country name

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
note
  • Unlike the statement of account (Rechnungsabschluss), a bank statement (Kontoauszug) is not legally binding and may therefore include bookings recorded between two dates. A bank statement does not include any statement number nor the mandatory disclaimer present in the statement of account.
  • Bank statements are idempotent and may be generated only with past dates.

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:

Copy
Copied
{
    "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",
    "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

booking_type valueDescription
CANCELLATION_BOOKING (exceptional case)Generic cancellation of a posted booking.
CANCELLATION_CARD_TRANSACTION (exceptional case)Correction of a card-related movement.
CANCELLATION_CARD_TRANSACTION_DIRECTCorrection of a peer-to-peer card transaction (e.g., MoneySend).
CANCELLATION_CHARGE_CARD (exceptional case)Correction of card-related charges.
CANCELLATION_CHARGE_DUNNINGCorrection of fees or charges resulting from the dunning process.
CANCELLATION_CHARGE_SEPA_DIRECT_DEBIT_RETURN (exceptional case)Correction of additional SDD return charges.
CANCELLATION_CRYPTO_EXCHANGE (exceptional case)Correction of a crypto-currency exchange operation.
CANCELLATION_CURRENCY_EXCHANGE_PARTNER (exceptional case)Correction of a currency exchange performed in cooperation between you and Solaris.
CANCELLATION_DIRECT_DEBIT (exceptional case)Correction of a SEPA Direct Debit collection (CORE scheme).
CANCELLATION_DOUBLE_BOOKING (exceptional case)Correction of a technical issue (e.g., if the payment has been submitted, booked, or executed twice).
CANCELLATION_INTERNAL_TRANSFER (exceptional case)Correction of a manual transaction.
CANCELLATION_INTERNATIONAL_CREDIT_TRANSFER (exceptional case)Correction of an international non-SEPA payment.
CANCELLATION_INTEREST_ACCRUED (exceptional case)Correction of interest accrual.
CANCELLATION_INTEREST_ANNUITYCancellation of an interest accrual. This booking is specific to loan products.
CANCELLATION_INTEREST_LOANCancellation of an irregular interest accrual. This booking is specific to loan products.
CANCELLATION_LOAN_PAYOUTCorrection of a loan payout. This booking is specific to loan products.
CANCELLATION_REBOOKING (exceptional case)Correction of a payment rerouting.
CANCELLATION_REBOOKING_INTEREST (exceptional case)Correction of an interest rerouting.
CANCELLATION_SEPA_CREDIT_TRANSFER_RETURN (exceptional case)Correction of a SEPA Credit Transfer return. This may be for both the sender/debtor (bounce back) and the receiver/creditor (recall by other side).
CANCELLATION_SEPA_DIRECT_DEBIT (exceptional case)Correction of a SEPA Direct Debit collection (B2B scheme).
CANCELLATION_SEPA_DIRECT_DEBIT_RETURN (exceptional case)Correction for the return of a SEPA Direct Debit (both CORE and B2B schemes).
CANCELLATION_TRANSFER_ANNUITYCorrection of irregular loan principal removal. This booking is specific to loan products.
CARD_DIRECT_DEBITSEPA Direct debit collection from a card account.
CARD_TRANSACTIONCard-related transaction (e.g., ATM withdrawal, payment, refund and etc.).
CARD_TRANSACTION_DIRECTPeer-to-peer card transaction (e.g., MoneySend).
CASH_DEPOSIT_RETAILA cash deposit to the customer's account using Viacash.
CASH_WITHDRAWAL_RETAILA cash withdrawal from the customer's account using Viacash.
CHARGE_ACCOUNT_MAINTENANCEAccount maintenance fee.
CHARGE_CARDCard-related charges.
CHARGE_DUNNINGFees or charges resulting from the dunning process.
ChargeRecallRequestCharge resulting from a recall request.
CHARGE_SEPA_DIRECT_DEBIT_RETURNAdditional charges for the return of a SDD collection.
ClosureBalanceTransferMoving remaining funds out of an account upon closure.
COMMISSION_OVERDRAFTAdditional interest charge upon exceeding the amount of the overdraft limit. This type of booking is booked separately from the main interest.
CREDIT_TRANSFER_CANCELLATION (exceptional case)Canceled Credit Transfer (including SEPA), either by customer request or due to Solaris internal checks.
CRYPTO_EXCHANGECashflow related to crypto-currency exchange operation.
CURRENCY_EXCHANGE_PARTNERCurrency exchange performed in cooperation between you and Solaris.
DIRECT_DEBITSEPA Direct Debit collection (either for creditor or debtor) using the CORE schema.
FOREIGN_PAYMENT (deprecated)Obsolete booking type. Replaced by INTERNATIONAL_CREDIT_TRANSFER.
INTEREST_ACCRUEDInterest accrued on the account.
INTEREST_ANNUITYInterest accrued for a period between the loan payout and the cancellation date (i.e., the withdrawal from the loan contract).
INTEREST_LOANIrregular interest accrual (e.g. for early repayment event). This booking is specific to loan products.
INTERNAL_TRANSFER (exceptional case)Manually executed transaction.
INTERNATIONAL_CREDIT_TRANSFERPayment via international non-SEPA payment scheme (usually SWIFT or TARGET2).
LOAN_PAYOUTMoney transfer from the loan account to the billing account when the loan payout is executed.
REBOOKINGPayment rerouting between accounts (e.g. routing of the payment to the correct account).
REBOOKING_INTERESTInterest rerouting between accounts.
SEPA_CREDIT_TRANSFERIncoming or outgoing SEPA Credit Transfer. This booking type is also used to categorize incoming TARGET2 payments.
SEPA_CREDIT_TRANSFER_RETURNResult of an R-Transaction for an accepted and executed SEPA Credit Transfer (e.g., if the other party's account does not exist or is blocked).
SEPA_DIRECT_DEBITSame as DIRECT_DEBIT, but for the B2B schema.
SEPA_DIRECT_DEBIT_RETURNResult of an R-Transaction for an accepted and executed SEPA Direct Debit (both CORE and B2B schemes), initiated by a third party (other side bank or clearing house). This may be for both the creditor (return) and the debtor (refund).
Target2CreditTransferA credit transfer sent via Target2 (as opposed to SEPA).
TRANSFER_ANNUITYIrregular loan principal removal (e.g., due to early repayment).
OTHERGeneric booking that does not fall into any of the listed categories.

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.