Appearance
Charges Configuration
Charges are fees and penalties applied to loan and savings accounts. They must be created before products, because products reference charges at configuration time. Getting charges right early saves significant rework later.
Charge vs. Penalty
Every charge in Fineract is classified as either a fee or a penalty:
| Type | penalty field | Behaviour |
|---|---|---|
| Fee | false | Applied automatically or by staff as a routine cost (disbursement fee, maintenance fee) |
| Penalty | true | Applied when a rule is violated (overdue penalty, bounced payment fee); counted separately in accounting and reporting |
The distinction matters for: GL account mapping (fees and penalties post to different income accounts), reporting (PAR metrics separate penalties from fees), and borrower communications.
Charge Calculation Types
How the charge amount is calculated:
| Code | Name | Meaning |
|---|---|---|
1 | Flat | Fixed currency amount (e.g., 10 USD per event) |
2 | Percentage of amount | % of outstanding principal (e.g., 1% of disbursed amount) |
3 | Percentage of amount + interest | % of principal + interest |
4 | Percentage of interest | % of interest component only |
5 | Percentage of amount disbursed | % calculated on disbursement amount specifically |
When Charges Apply (Charge Time Types)
The chargeTimeType field controls the trigger:
| Code | Name | Applies to | Triggered when |
|---|---|---|---|
1 | Disbursement | Loans | Loan is first disbursed |
2 | Specified due date | Loans | A specific calendar date set at account level |
3 | Instalment fee | Loans | Every repayment instalment |
4 | Overdue | Loans | An instalment becomes overdue (COB applies this) |
5 | Loan maturity | Loans | Loan reaches its maturity date |
6 | Monthly fee (savings) | Savings | Monthly, on a configured day of month |
7 | Annual fee (savings) | Savings | Annually, on a configured date |
8 | Withdrawal fee | Savings | Each savings withdrawal |
9 | Savings no activity fee | Savings | Account is inactive for a configured period |
10 | Tranche disbursement | Multi-tranche loans | Each subsequent tranche is disbursed |
12 | Overdue maturity date fee | Loans | Loan is not closed by maturity date |
Charge Payment Modes (Loan Charges)
| Code | Name | Meaning |
|---|---|---|
0 | Regular | Charged to the loan account, collected on repayment |
1 | Up-front (capitalised) | Added to principal at disbursement |
Creating a Charge via API
bash
POST /fineract-provider/api/v1/charges
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/jsonExample 1: Flat disbursement fee
json
{
"name": "Loan Origination Fee",
"currencyCode": "USD",
"amount": 25.00,
"chargeAppliesTo": 1,
"chargeTimeType": 1,
"chargeCalculationType": 1,
"chargePaymentMode": 0,
"penalty": false,
"active": true,
"locale": "en"
}Example 2: Percentage overdue penalty
json
{
"name": "Late Payment Penalty",
"currencyCode": "USD",
"amount": 2.0,
"chargeAppliesTo": 1,
"chargeTimeType": 4,
"chargeCalculationType": 2,
"chargePaymentMode": 0,
"penalty": true,
"feeInterval": 1,
"feeFrequency": 2,
"active": true,
"locale": "en"
}feeInterval and feeFrequency on overdue charges control how often the penalty is reapplied - in this example, every 1 month while the instalment remains unpaid.
Example 3: Monthly savings maintenance fee
json
{
"name": "Monthly Account Fee",
"currencyCode": "USD",
"amount": 3.00,
"chargeAppliesTo": 2,
"chargeTimeType": 6,
"chargeCalculationType": 1,
"penalty": false,
"feeOnMonthDay": "01 January",
"monthDayFormat": "dd MMMM",
"active": true,
"locale": "en"
}chargeAppliesTo: 1 = Loans, chargeAppliesTo: 2 = Savings.
Field Reference
| Field | Required | Meaning |
|---|---|---|
name | Yes | Display name for this charge |
currencyCode | Yes | ISO 4217 currency code |
amount | Yes | Base amount (flat value or percentage rate) |
chargeAppliesTo | Yes | 1 = Loan, 2 = Savings, 3 = Client |
chargeTimeType | Yes | When the charge triggers (see table above) |
chargeCalculationType | Yes | How amount is calculated (see table above) |
chargePaymentMode | Loan only | 0 = Regular, 1 = Up-front |
penalty | Yes | true for penalties, false for fees |
active | Yes | true to make available for use on products |
minCap | No | Minimum charge amount when using percentage calculation |
maxCap | No | Maximum charge amount when using percentage calculation |
feeInterval | Overdue/recurring | How often the charge repeats |
feeFrequency | Overdue/recurring | Frequency unit: 0=days, 1=weeks, 2=months, 3=years |
Attaching Charges to a Loan Product
Charges are referenced in the charges array when creating or updating a loan product:
json
{
"name": "Standard Personal Loan",
"charges": [
{ "id": 1 },
{ "id": 3 }
]
}These become the default charges applied to every loan account created from this product. Charges can also be added or removed at the individual loan account level before or after disbursement.
Adding a Charge to an Existing Loan Account
bash
POST /fineract-provider/api/v1/loans/{loanId}/chargesjson
{
"chargeId": 4,
"amount": 15.00,
"dueDate": "01 April 2025",
"dateFormat": "dd MMMM yyyy",
"locale": "en"
}For specified due date charges, include dueDate. For disbursement and instalment charges, dueDate is not required.
Waiving a Charge
Staff can waive a specific charge on a loan account when appropriate:
bash
POST /fineract-provider/api/v1/loans/{loanId}/charges/{chargeId}?command=waiveWaived charges appear in the loan transaction history with type WAIVE_CHARGES and are reflected in the accounting entries.
Listing and Managing Charges
bash
# List all active charges
GET /fineract-provider/api/v1/charges
# List only loan charges
GET /fineract-provider/api/v1/charges?chargeAppliesTo=1
# Get a specific charge
GET /fineract-provider/api/v1/charges/{chargeId}
# Update a charge (name, amount, active status)
PUT /fineract-provider/api/v1/charges/{chargeId}
# Delete a charge (only if not used by any product or account)
DELETE /fineract-provider/api/v1/charges/{chargeId}Recommended Charge Setup for a New Deployment
Before creating any loan or savings products, set up at minimum:
| Charge | Type | Applies to | Typical amount |
|---|---|---|---|
| Loan origination fee | Flat, disbursement | Loans | Fixed amount or 1-3% |
| Late payment penalty | % of amount, overdue | Loans | 1-2% per month |
| Loan instalment processing fee | Flat, instalment | Loans | Small fixed amount |
| Savings withdrawal fee | Flat, withdrawal | Savings | Fixed per withdrawal |
| Monthly account maintenance | Flat, monthly | Savings | Fixed per month |
Creating these first means products can reference them from day one.
Common Mistakes
| Mistake | Effect | Fix |
|---|---|---|
| Creating a product before its charges exist | Product creation fails or charge references are missing | Always create charges before products |
Using penalty: false for a late payment charge | Charge appears as a fee in reports and accounting | Set penalty: true for all late/overdue charges |
Not setting minCap/maxCap on % charges | Very small or very large loans get disproportionate charges | Always cap percentage charges |
| Deleting an active charge in use | API returns a 403 or conflict error | Deactivate ("active": false) instead of deleting |