Fee collection
Overview
The Solaris fee collection API allows you to request the collection of fees from your customers for banking services, such as account maintenance and ATM withdrawals, in a regulatory-compliant manner.
As the Bank, Solaris will collect the applicable banking service fees that you request from your customers' accounts and hold such fees in its own settlement account. Then, on a monthly basis, Solaris will transfer the sum of the collected fees to an account you own.
See the API reference for a full list of fee types you can collect with this endpoint.
This page explains the process behind fee collection and how to implement the relevant API endpoints.
note
To collect fees not related to banking services, please consult the billing accounts guide.
Fee collection account structure
The fee collection feature consists of three different account types opened across three separate partner IDs.
- (Partner ID 1) End customer accounts: Your customers' accounts that they open with you. Solaris collects the fees directly from these accounts. Solaris assigns this partner ID to you during onboarding.
- (Partner ID 2) Solaris settlement account: A settlement account that Solaris opens and manages for the sake of collecting fees from your end customers. You must have one settlement account per branch that you have in your solution. You do not have access to this partner ID or these accounts, as they are owned and managed by Solaris.
- (Partner ID 3) Partner billing account: A billing account in your name where Solaris pays out the fees collected from the customers at the end of each month.
Fee collection process
Here is the process for collecting banking service fees from your customers:
- Contact your Partner Manager to request the creation of a Solaris settlement account, a billing account, and a clearing profile.
-
Before you can collect a fee from a customer, they must have agreed to the relevant fee types and corresponding pricing as specified in the latest version of the Solaris Terms and Conditions.
- Whenever existing fees and their related pricing change, the customer must first consent to the new Terms and Conditions before you can request the new fee amount. See the Terms and Conditions consent log guide for information on how to handle this event.
- Call the POST Create fee collection transaction endpoint to initiate the collection process for each fee that you wish to collect from each customer.
-
When the API call succeeds, Solaris will create a booking for the fee on the customer's account and store the funds in the Solaris settlement account.
- See the API reference for a list of booking types related to fee collection.
- On a monthly basis, Solaris will pay out the collected fees to your billing account.
- If your customer requests a refund, then you must create a debit clearing transaction to return the funds to their account.
attention
You must call this endpoint each time you wish to collect a fee from each customer.
Overdue customers
Fee collection transactions will only succeed if the customer has a positive available balance on their account. If Solaris attempts to collect the fee and fails due to insufficient balance, then the customer will become overdue to Solaris for the banking fee.
Partners are responsible for keeping track of overdue customers and notifying them when they are overdue for banking fees. You may send reminders using your preferred method (e.g., email, in-app notification) to inform customers that they must ensure that there are sufficient funds in their account (i.e., top up their account) to collect the overdue fee(s). You can monitor the customer's balance changes to trigger the next fee collection attempt.
Closure due to outstanding fees
If a customer does not pay their outstanding banking fees after a period
of time defined in your cooperation agreement with Solaris, then you must
request an account closure with the reason RELATIONSHIP_TERMINATION
and
notify the customer.
The customer has the opportunity during the standard closure notice period to top up their account with the required amount and avoid account closure. If they do not, then the account will be closed.
Fee collection API endpoints
Implement the following API endpoints to request fee collections from your customers:
POST Create fee collection transaction
note
You may only request fee collection for fee types that Solaris has enabled for you. Contact your Partner Manager for more information about enabling different fee types.
This endpoint creates a fee transaction on the account specified in the URL. Solaris will debit the amount from the customer's account and transfer the funds to a Solaris settlement account. Each month, Solaris will pay out the amounts collected from fee transactions to your partner account.
Request URL:
POST /v1/accounts/{account_id}/transactions/fees
Request example:
{
"type": "ChargeAccountMaintenance",
"amount": {
"value": 499,
"currency": "EUR"
},
"initiator_reference": "2022_08_acc_maint",
"idempotency_key": "653e91ae-7e93-4106-a33c-00607dae851e"
}
Response example:
{
"type": "ChargeAccountMaintenance",
"amount": {
"value": 499,
"currency": "EUR"
},
"reconciliation_id": "938cfdf93ef54bdcbd4e955584da3bf0fct",
"initiator_reference": "2022_08_acc_maint",
"original_transaction_id": "6d4659e500ef4b10aa48d6b08d0d3e7b"
}
Click here to read the full API reference.
GET List fee transactions for an account
This endpoint returns an array containing all fee transactions created for the account specified in the request URL.
Request URL:
GET /v1/accounts/{account_id}/transactions/fees
Response example:
[
{
"type": "ChargeAccountMaintenance",
"amount": {
"value": 499,
"currency": "EUR"
},
"reconciliation_id": "938cfdf93ef54bdcbd4e955584da3bf0fct",
"initiator_reference": "2022_08_acct_maint",
"original_transaction_id": "6d4659e500ef4b10aa48d6b08d0d3e7b"
}
]
Click here to read the full API reference.
Refunds
In the event that you must refund a fee collected from a customer, you must create a debit clearing transaction to transfer the funds from your billing account to the customer's account.
note
You must have a clearing profile set up for you by Solaris before you can initiate this type of transaction.
POST Create debit clearing transaction
This endpoint initiates a transaction from the account specified in the clearing profile (i.e., your billing account) to the account specified in the request URL.
Please note the following:
- Pass the customer's account ID in the request URL.
- The debit clearing transaction must use the same booking type as the one used when you collected the fee from the customer.
- Pass the booking ID of the original fee transaction as the value of the
initiator_reference
property in the request.
Request URL
POST /v1/accounts/{account_id}/debit_clearing_transactions
Request properties:
amount
: The fee amount to be returned to the customer.booking_type
: The booking type to use for the debit clearing transaction. Must match the booking type used in the original fee collection.description
: A description of the transaction.clearing_profile_id
: ID of the clearing profile to use for the debit clearing transaction. Solaris will provide this after creating the clearing profile.reference
: A unique reference for the transaction.initiator_reference
: Use the booking ID of the original fee collection transaction.
Response
Solaris will initiate the clearing transaction, and the API will respond with details of the transaction.