# Fee Collection

The **Fee Collection API** allows you to charge your customers for banking services—such as account maintenance, card issuance, or ATM withdrawals—in a compliant manner.

Solaris debits the fee from the customer's account, holds it in a settlement account, and transfers the aggregated total to your billing account on a monthly basis.

Scope Definition
**Banking Fees vs. Commercial Fees**

* **Fee Collection (This Guide):** Strictly for **banking services** regulated by your partner agreement (e.g., Monthly Account Fee).
* **Billing Accounts:** For **commercial fees** (e.g., other subscription fees).
  * To collect commercial fees, refer to the [Billing Accounts Guide](/guides/digital-banking/billing-accounts).


## Account architecture

The fee collection process moves funds across three distinct account levels.

Diagram: Fee collection process
| Account Level | Ownership | Function |
|  --- | --- | --- |
| **1. Customer Account** | End Customer | **Source of Funds.** The fee is debited directly from here. |
| **2. Settlement Account** | Solaris (Internal) | **Holding.** Solaris collects fees here instantly. You cannot access this account directly. |
| **3. Billing Account** | Partner (You) | **Destination.** Aggregated fees are paid out to this account monthly. |


## Prerequisites

Before collecting fees, you must ensure compliance and configuration.

1. **Settlement Setup:** Contact your Partner Manager to create your **Settlement Account** and **Clearing Profile** (required for refunds).
2. **Customer Consent:** The customer must have agreed to the *latest* version of your Terms and Conditions (T&Cs).
  * If you update your pricing, the customer must re-consent via the [Terms and Conditions API](/guides/compliance/terms-and-conditions-consent-log) before you can charge the new amount.


## Operational workflows

### 1. Collect a fee

Call this endpoint to debit a specific fee type from a customer's account.

* **Frequency:** You must call this for **each** fee event (e.g., once per month for maintenance).
* **Idempotency:** Always use a unique `idempotency_key` to prevent double-charging.


**Field Logic:**

| Field | Description |
|  --- | --- |
| `type` | **Mandatory.** Must match one of the allowed Enums (see list below). |
| `initiator_reference` | **Your Label.** A string you define to identify this batch or event (e.g., `Maint_Jan_2025`). |
| `original_transaction_id` | **Conditional.** If this fee is related to a specific user action (e.g., an ATM fee), pass the **Booking ID** of that ATM transaction here. |



```json
// POST /v1/accounts/{account_id}/transactions/fees
{
  "type": "ChargeAccountMaintenance",
  "amount": {
    "value": 499,
    "currency": "EUR"
  },
  "initiator_reference": "Maint_Jan_2025",
  "idempotency_key": "653e91ae-7e93-4106-a33c-00607dae851e",
  "valuta_date": "2025-01-01"
}
```

Create Fee
View endpoint definition.

List Fees
View fee history.

### 2. Refund a fee

To refund a fee (e.g., if charged in error), you must create a **Debit Clearing Transaction**.

**Requirements:**

* **Clearing Profile:** You must have a valid `clearing_profile_id` (provided by Solaris).
* **Booking Type:** Must match the original fee type (e.g., `ChargeAccountMaintenance`).


**Field Logic:**

| Field | Requirement & Description |
|  --- | --- |
| `amount` | **Mandatory.** The exact amount to be returned to the customer. |
| `booking_type` | **Constraint.** Must match the `type` used in the original fee collection (e.g., if you refund a maintenance fee, use `ChargeAccountMaintenance`). |
| `clearing_profile_id` | **Configuration.** The ID of the clearing profile provided by your Partner Manager. This determines which internal account funds the refund. |
| `initiator_reference` | **Traceability.** Pass the `reconciliation_id` from the original Fee Response here. This links the refund to the original charge in your reports. |
| `reference` | **Mandatory.** A unique ID you generate for this specific refund action. |


**Request:**


```json
// POST /v1/accounts/{account_id}/debit_clearing_transactions
{
  "amount": {
    "value": 499,
    "currency": "EUR",
    "unit": "cents"
  },
  "booking_type": "ChargeAccountMaintenance",
  "clearing_profile_id": "1c0eda0b559825ef456b21d81f4ee962pacp",
  "description": "Refund for Jan Maintenance",
  "reference": "REFUND-JAN-01",
  "initiator_reference": "938cfdf93ef54bdcbd4e955584da3bf0fct"
}
```

**Response:**


```json
{
  "id": "3f4e761f500e4c11a6627b4d90daaec4",
  "status": "ACCEPTED",
  "account_id": "06659ff514934b28800b5650d109cacc",
  "amount": {
    "value": 499,
    "unit": "cents",
    "currency": "EUR"
  },
  "description": "Refund for Jan Maintenance",
  "booking_type": "ChargeAccountMaintenance",
  "valuta_date": "2025-01-15",
  "transaction_type": "CLEARING_TRANSACTION",
  "reference": "REFUND-JAN-01",
  "initiator_reference": "938cfdf93ef54bdcbd4e955584da3bf0fct"
}
```

Refund Fee
View clearing endpoint.

## Exception handling

You must handle scenarios where fees cannot be collected.

### Overdue customers

If a fee collection fails due to **insufficient funds**:

1. **No Retry Logic:** The API returns an error. Solaris does *not* auto-retry.
2. **Partner Responsibility:** You must track this failure internally.
3. **Action:** Notify the customer via email/push to top up their account. Monitor the balance and retry the API call when funds are available.


### Forced closure

If a customer refuses to pay outstanding fees for a duration defined in your cooperation agreement:

1. **Terminate:** You must request an account closure with the reason `RELATIONSHIP_TERMINATION`.
2. **Notice Period:** The customer has a legal notice period to settle the debt.
3. **Closure:** If unpaid, the account is closed, and the debt handling proceeds according to your risk processes.


## Supported fee types

You may only collect fees that are enabled in your partner contract. You must use the exact **Enum** string from the list below.

details
summary
strong
Click to view the full Enum List
br
**Account Fees**

* `ChargeAccountMaintenance`
* `ChargeAdditionalAccountMaintenance`
* `ChargeSharedAccount`
* `ChargeAuthorizedUser`


**Card Fees**

* `ChargeCard` (Issuance)
* `ChargeCardDelivery`
* `ChargeVirtualCard`
* `ChargeReissuePhysicalCard`
* `ChargeReissueVirtualCard`
* `ChargeAdditionalPhysicalCard`
* `ChargeAdditionalVirtualCard`
* `ChargeCardMaintenance`
* `ChargeTopUpCard`


**Transaction Fees**

* `ChargeATM`
* `ChargeATMForeignCurrency`
* `CashDepositRetail`
* `CashWithdrawalRetail`
* `ChargeSEPAInstantOutgoing`
* `ChargeSEPAInstantIncoming`
* `ChargeManualSepaTransferPartner`
* `ChargeIncomingSwift`
* `ChargeFXCardTransaction`
* `ChargeGamblingTransactionPartner`
* `ChargeGamblingOrCashEquivalent`


**Packages**

* `BoosterPackage`