Credit Balance for Revolving Loans

Credit Balance (sometimes called negative balance) is a store of the customer's own money on a revolving loan account. It is not part of what the customer owes the bank — it is money the bank owes back to the customer — so it is tracked separately from the loan's principal, interest, fees, and penalties.

Customers build up a Credit Balance in two ways:

• By paying more than they currently owe (an overpayment), instead of the excess amount being rejected.
• By making a direct deposit to top up the balance ahead of a future purchase.

Once funds are in the Credit Balance, they can be used to cover a future disbursement above the account's approved credit limit, or drawn down automatically to repay what's due.

note

This page documents Release 1 of Credit Balance, which is available via the API only — there is no Mambu UI to configure or use this feature yet. Release 1 covers product and account settings, overpayments, deposits, and disbursements. Refunds that exceed the amount owed are also routed to the Credit Balance; see Refunds below.

Terminology

• Credit Balance — money that belongs to the customer, stored on the loan account. It does not accrue interest and is not included in the Total Balance.
• Total Balance (Total Debt) — the total amount the customer owes: principal + interest + fees + penalties.
• Available Balance — the amount the customer can still disburse: Loan Amount − Total Balance. When Credit Balance is enabled, funds in the Credit Balance add to what can be disbursed.
• Overpayment — a repayment for an amount greater than the Total Balance.
• Auto-allocation — the product setting that determines what happens to the excess amount from an overpayment. Two options are supported: Cover Balance Amount, and Cover Due Amount.

How Credit Balance affects other balances

• Repayments can increase the Credit Balance — if an overpayment is made and the excess is auto-allocated to it — while decreasing the Total Balance.
• Disbursements can decrease the Credit Balance, if there are funds available in it, while increasing the Total Balance.
• Refunds can increase the Credit Balance, if the refunded amount is more than what's owed on the disbursement being refunded.

Enabling Credit Balance on a product

Credit Balance is configured at the loan product level, via the API only. When creating or updating a Revolving Credit product, set:

Field	Description
isEnabled	Turns Credit Balance on or off for accounts created from this product.
maxCreditBalance	The maximum amount a Credit Balance can hold on accounts under this product.
autoAllocation	The auto-allocation behavior for overpayments: COVER_BALANCE_AMOUNT, or COVER_DUE_AMOUNT.

New accounts created from the product inherit these settings. For existing accounts, the same settings can be edited individually at the account level via the API — they are not automatically kept in sync with later changes to the product.

Migrating existing accounts onto Credit Balance

Enabling Credit Balance on a product does not retroactively change accounts that already exist under it. To bring all of them onto Credit Balance at once, Mambu can run a private-API migration job that applies the product's default Credit Balance settings to every account created from a given productTypeKey. This requires the customer's approval and the productTypeKey to migrate — it is not a self-service action in Release 1.

Overpayment (Cover Balance Amount)

When a customer submits a repayment for more than the Total Balance and the account's autoAllocation is COVER_BALANCE_AMOUNT, Mambu:

1. Pays off the due amount and any remaining balances on future installments, as far as the repaid amount allows.
2. Adds any amount still left over to the account's Credit Balance, as long as doing so does not exceed maxCreditBalance.

If the input amount would push the Credit Balance past maxCreditBalance, the repayment is rejected.

If Credit Balance is not enabled on the product, an overpayment above the Total Balance is rejected, as it is today.

Overpayment (Cover Due Amount)

When a customer submits a repayment for more than the Total Balance and the account's autoAllocation is COVER_DUE_AMOUNT, Mambu pays off only the amount currently due and routes any repayment funds left over straight to the account's Credit Balance, as long as doing so does not exceed maxCreditBalance.

Unlike Cover Balance Amount, the excess is not applied to future installments first — it goes directly to the Credit Balance.

Depositing funds to the Credit Balance

Customers can top up their Credit Balance directly, ahead of a future purchase, using a dedicated CREDIT_BALANCE_DEPOSIT transaction. This is available via the API only in Release 1.

A deposit is only allowed when:

• The resulting Credit Balance (current balance + deposit amount) does not exceed maxCreditBalance.
• The account's Total Balance is zero, unless the product has allowDepositWithDebitBalance enabled — in which case a deposit is allowed even while the account has an outstanding balance.
• The user has the permission to make CREDIT_BALANCE_DEPOSIT transactions.

warning

Backdated deposits are not allowed. A deposit is always posted using the current date.

Adjusting a deposit

A CREDIT_BALANCE_DEPOSIT transaction can be adjusted (reversed) like other loan transactions. Adjusting a deposit reduces the Credit Balance by the original deposit amount and marks the original transaction as adjusted.

Disbursement using the Credit Balance

If an account has funds in its Credit Balance, a disbursement can draw on them to fund an amount above what would otherwise be available. The disbursement is posted as a single transaction, with the portion funded from the Credit Balance recorded alongside it.

The maximum disbursable amount becomes:

Loan Amount + Credit Balance − Total Balance − authorization holds

The Credit Balance is reduced by whatever portion of the disbursement it funded.

Example: overpayment followed by a disbursement

This example walks through the full flow, from an overpayment through to a later disbursement funded from the resulting Credit Balance. The account's approved Loan Amount is £500, and autoAllocation is COVER_BALANCE_AMOUNT.

Total Balance due: £100

Repayment of £130:
  -> £100 pays off the amount due           (Total Balance: £100 -> £0)
  -> £30 excess is added to the Credit Balance (Credit Balance: £0 -> £30)

Later, a disbursement of £520 is requested:
  -> The first £30 is funded from the Credit Balance
  -> The remaining £490 is disbursed from the loan itself
     (Credit Balance: £30 -> £0, Total Balance: £0 -> £510)

Refunds

When a refund is processed for more than what's currently owed on the disbursement being refunded, the excess is credited to the Credit Balance instead of being rejected. Refunds themselves — partial and full refunds and interest recalculation — are a separate feature; see Refunds for Revolving Loans.

Closing an account with a Credit Balance

Because a Credit Balance is money Mambu owes back to the customer, Mambu blocks the following actions on a Revolving Credit account for as long as its Credit Balance is greater than zero:

• Pay Off
• Write Off
• Reschedule
• Refinance
• Close

The validation applies regardless of the channel used — the same check runs for the UI and the API — and blocking one of these actions displays a clear error message explaining that the account cannot be closed because of an existing Credit Balance.

Accounting

Credit Balance is tracked as a liability. A new GL financial resource, CREDIT_BALANCE_PAYABLE, must be configured in the product's Accounting Rules before any Credit Balance transactions can be processed.

Financial action	Debit	Credit
Overpayment allocated to Credit Balance	Transaction Source (Asset +)	Portfolio Control (Asset –) + Credit Balance (Liability +)
Deposit to Credit Balance	Transaction Source (Asset +)	Credit Balance (Liability +)
Disbursement funded from Credit Balance	Credit Balance (Liability –)	Portfolio Control (Asset +)

Limitations

Currently not supported:

• Mambu UI support — Credit Balance can only be configured and used via the API.
• Auto-collection — an end-of-day process that draws down the Credit Balance to cover due amounts automatically.
• A standalone withdrawal transaction, or transferring Credit Balance funds out of the account.
• Backdated transactions — deposits, overpayments, and disbursements are all rejected or processed as if Credit Balance were disabled, throwing the usual ExcessPaymentException or AmountNotAvailableException if the amount exceeds what's otherwise available.
• Credit Arrangement integration — the Credit Balance is not currently reflected in the Credit Arrangement's total available balance.
• Interest on the Credit Balance — funds held in it never accrue interest.

Frequently asked questions

Can a customer withdraw money out of their Credit Balance?

Not in Release 1. There is no standalone withdrawal transaction yet. The only way funds leave the Credit Balance is by funding a disbursement.

Does the Credit Balance affect the Total Balance?

No. The Credit Balance is the customer's own money and is never included in the Total Balance calculation.

What happens to an overpayment if Credit Balance is not enabled on the product?

The repayment is rejected if it exceeds the Total Balance, the same as it is today.

Can I backdate a transaction that would add to the Credit Balance?

No. Backdated deposits, overpayments, and disbursements are all treated as if Credit Balance were disabled — an amount above what's otherwise due or available throws the usual exception.

Can I close a Revolving Credit account that still has a Credit Balance?

No. Pay Off, Write Off, Reschedule, Refinance, and Close are all blocked while the account's Credit Balance is greater than zero, whether the action is attempted via the UI or the API. The funds need to leave the Credit Balance — for example by funding a disbursement — before the account can be closed.

Can I move existing accounts under a product onto Credit Balance after enabling it?

Yes. Mambu can run a private-API migration job that applies the product's default Credit Balance settings to every existing account created from a given productTypeKey. This requires your approval and the productTypeKey to migrate — it's not available as self-service in Release 1.