# Savings

Savings (branded "Auto-Savings" in the dashboard) turns part of your incoming Mobile Money payments into a savings pot. You pick a savings period that defines a lock duration, an interest rate, and an early-exit fee, switch auto-savings on, and a configured percentage of every successful collection is set aside automatically into a maturing, interest-bearing deposit. You can also transfer money in by hand, withdraw at any time, and preview the net proceeds of a withdrawal before you commit.

:::note
Savings is managed in the dashboard today. It is not part of the public developer API (`/v1`, `X-API-Key`), which only exposes core Payments (create, list, status). There is no savings endpoint, field, or webhook available to API-key holders. The only indirect touchpoint is that a public collection via `POST /v1/payments` can trigger an auto-savings deposit server-side. Exposing Savings on the public API is planned. The underlying collection is the same primitive documented in [Payments & Collections](/en/payments/overview).
:::

## How it works

Savings is built from three things.

- **Account.** Your business has one savings account (`BusinessSavings`). It tracks your total saved balance, what is available to withdraw, and accumulated interest.
- **Period.** A savings period defines the terms of every deposit made while it is active: a lock duration in months, an interest rate paid at maturity, and an early-withdrawal fee rate.
- **Record.** Each deposit is a dated `BusinessSavingsRecord`. A record is stamped at creation with the interest rate, fee rate, and a maturity date computed from the period in effect at the time. Records mature and earn interest independently.

Money originates as a normal collection into your business's available balance. Saving (whether automatic or manual) debits that balance and credits the savings account, creating a new record. Money only leaves savings when you withdraw, which credits the proceeds back to your business balance.

## Savings periods

A period is the term sheet for the deposits you make under it. Each period defines three values.

| Field | Meaning |
| --- | --- |
| Duration | The lock length in months. A deposit's maturity date is the deposit date plus this many months. |
| Interest rate | The percentage paid once, at maturity, on the record's balance. |
| Early-exit fee rate | The percentage charged if you withdraw a record before it has matured. |

You select a period when you turn savings on. A record locks in the terms of whichever period was active when it was created, so changing your account's current period later does not alter existing records.

## Turning auto-savings on and off

You turn savings on by choosing a period and an auto-savings percentage. This creates your `BusinessSavings` account, sets its current period, and flips your business settings to `isAutoSavingsOn = true` with the percentage you chose.

Turning savings off only sets `isAutoSavingsOn = false`. Your saved funds and existing records stay exactly where they are and keep maturing and earning interest. Auto-deposits simply stop. The money remains until you withdraw it.

:::info
Turning off auto-savings is not a withdrawal. To get money back into your spendable business balance, withdraw it explicitly.
:::

## Auto-save on collections

When auto-savings is on, every collection that settles to `SUCCESS` triggers a deposit. The amount set aside is a straight percentage of the collected amount:

```
savingsAmount = amount * autoSavingsPercentage / 100
```

There is a guard: if `savingsAmount` falls below the platform's minimum savings threshold (`minSavingsAmount`), the deposit is skipped for that collection. Small collections do not generate dust deposits.

When a deposit does run, two things happen:

1. Your business balance is debited by `savingsAmount` (reason `INTERNAL_TRANSFER_TO_SAVINGS`).
2. A `DEPOSIT` transaction of type `AUTO_SAVINGS` is recorded and a new savings record is created, stamped with the current period's interest rate, fee rate, and a maturity date.

:::caution
Auto-save is best-effort. If the deposit step fails after a collection succeeds, the failure is logged and swallowed, not retried. The collection itself is unaffected and your funds remain in your business balance.
:::

## Manual transfers into savings

You can push money into savings at any time, independent of collections. A manual transfer debits your business balance (reason `MANUAL_SAVINGS_TRANSFER`) and creates a deposit record of type `MANUAL`, using the same period terms as an auto-deposit.

This is useful for topping up your savings pot directly rather than waiting for the auto-save percentage to accumulate it.

## Maturity and interest accrual

Interest is virtual until a record matures. A scheduled maturity job runs in the background, finds records whose maturity date has passed, and processes them.

For each matured record, interest is accrued once:

```
interest = balanceLeft * interestRate / 100
```

The accrued interest is rolled into your account's accumulated and available balances. There is no compounding: interest is a one-time accrual at maturity, computed on the record's remaining balance using the rate stamped on that record.

## Balances explained

Your savings account exposes several balances that mean different things.

| Balance | Meaning |
| --- | --- |
| `balance` / `totalBalance` | The total principal saved across all records. |
| `availableBalance` | What you can withdraw, including matured interest already rolled in. |
| Accumulated interest | Interest earned from records that have reached maturity. |

The distinction matters at withdrawal time: matured records have earned their interest, while records still inside their lock period have not, and withdrawing them early costs a fee and forfeits their pending interest.

## Withdrawals

Withdrawals consume records **oldest-first (FIFO)**. Starting from your earliest deposit, records are drawn down until the requested amount is covered. How each record pays out depends on whether it has matured.

- **Matured record.** Pays out its principal plus the interest it earned at maturity.
- **Un-matured record.** Pays out its principal minus the early-exit fee, and forfeits the interest it would have earned. The fee uses the fee rate stamped on that record.

The net of the whole withdrawal (principal, minus early-exit fees, plus matured interest) is credited back to your business balance with reason `SAVINGS_WITHDRAWAL`, and your account aggregates are recalculated.

:::caution
Withdrawing an un-matured record is an early exit. You pay the record's early-exit fee and you forfeit the interest that record would have earned at maturity. Where possible, withdraw only what your matured records cover to avoid fees.
:::

## Previewing a withdrawal

Before committing, you can preview exactly what a withdrawal will cost. The dashboard's withdrawal preview walks your records FIFO for a given amount and returns:

- **Fees** charged on any un-matured records consumed.
- **Interest forfeited** by exiting those records early.
- **Net amount** that would actually land back in your business balance.

This lets you see the true proceeds, and the penalty, of pulling out a given amount before you confirm.

## Money movement and history

All savings money stays on-platform. Saving moves funds from your business balance into the savings account; withdrawing moves them back. Savings never sends money off-platform on its own. Paying out to a Mobile Money line is a separate balance-withdrawal product.

Every action is recorded as a savings transaction, so deposits (auto and manual) and withdrawals show up in your savings history in the dashboard. Currency follows the platform default, XAF.

## Where this lives

Savings is a dashboard product. Configure auto-savings, transfer in, preview, and withdraw at [app.kwiknkap.com](https://app.kwiknkap.com).

To collect Mobile Money payments programmatically today, use the public Payments API documented in [Payments & Collections](/en/payments/overview). A successful collection there, with auto-savings on, is exactly what triggers an automatic deposit.