A Spring Boot plugin that extends Apache Fineract to provide self-service banking capabilities to end users. It lets customers register, authenticate, view their accounts, transfer funds, and manage their financial products — all without staff intervention.
- What Is This?
- What Does It Do?
- Architecture Overview
- Prerequisites
- Getting Started
- API Reference
- Contributing
- History
- Important Notices
- License
Apache Fineract is an open-source core banking platform. Out of the box, its APIs are designed for back-office staff — loan officers, tellers, and administrators. There is no built-in mechanism for a bank's actual customers to log in, check their balances, or initiate transfers themselves.
This plugin bridges that gap. It adds a complete set of customer-facing REST APIs (under /v1/self/...) that sit on top of Fineract's core. Think of it as the backend for a mobile banking app or a customer web portal.
Key point: This is a plugin, not a standalone application. It ships as a JAR that you drop into your existing Fineract deployment. It extends Fineract at runtime — no forking, no patching of Fineract source code required.
| Capability | Description |
|---|---|
| Self-Registration & Enrollment | Customers can sign up, receive a verification token (via email/SMS), and activate their account. |
| Authentication | Dedicated login endpoint with HTTP Basic Auth support, 2FA compatibility, and login attempt notifications. |
| Password Recovery | Request a password reset token and renew the password — all self-service. |
| Client Profile | View personal details, profile images, charges, and transaction history. |
| Savings Accounts | List savings accounts, view balances, transactions, charges, and apply for new savings products. |
| Loan Accounts | Browse loan details, repayment schedules, charges, guarantors, and apply for new loans. |
| Share Accounts | View share account holdings and apply for share products. |
| Fund Transfers | Transfer between own accounts or to third-party beneficiaries (with configurable daily/per-beneficiary limits). |
| Beneficiary Management | Add, update, and delete third-party transfer beneficiaries. |
| Product Discovery | Browse available savings, loan, and share products. |
| Reports | Run pre-configured financial reports scoped to the authenticated user. |
| Surveys & Scorecards | Participate in surveys and view scorecards. |
| Notifications | Event-driven email/SMS notifications for login activity and account activation (with cooldown and SMTP fallback). |
┌─────────────────────────────────────────────────────────┐
│ Client Applications │
│ (Mobile App / Web Portal / Chatbot) │
└────────────────────────┬────────────────────────────────┘
│ HTTPS /v1/self/*
▼
┌─────────────────────────────────────────────────────────┐
│ Self Service Plugin (this repo) │
│ ┌─────────────┐ ┌──────────┐ ┌──────────────────────┐ │
│ │ Registration│ │ Security │ │ Notifications │ │
│ │ & Enrollment│ │ & Auth │ │ (Email / SMS) │ │
│ └─────────────┘ └──────────┘ └──────────────────────┘ │
│ ┌─────────────┐ ┌──────────┐ ┌──────────────────────┐ │
│ │ Clients │ │ Savings │ │ Loans │ │
│ └─────────────┘ └──────────┘ └──────────────────────┘ │
│ ┌─────────────┐ ┌──────────┐ ┌──────────────────────┐ │
│ │ Shares │ │ Transfers│ │ Products / Reports │ │
│ └─────────────┘ └──────────┘ └──────────────────────┘ │
└────────────────────────┬────────────────────────────────┘
│ delegates to
▼
┌─────────────────────────────────────────────────────────┐
│ Apache Fineract Core │
│ (fineract-provider, fineract-core, etc.) │
│ Multi-Tenant DB │
└─────────────────────────────────────────────────────────┘
Tech stack: Java 25 · Spring Boot 4 · Spring Security (Basic Auth + OAuth2) · JAX-RS · JPA/EclipseLink · Liquibase · Lombok · Swagger/OpenAPI
| Requirement | Version |
|---|---|
| Java (JDK) | 25 |
| Maven | 3.6+ (or use the included ./mvnw wrapper) |
| Apache Fineract | 1.16.0-SNAPSHOT (develop branch) |
| Database | PostgreSQL or MySQL (managed by Fineract) |
Note: You do not need to install Fineract from source to use the plugin. You just need a running Fineract instance (JAR or Docker) to deploy the plugin into.
git clone https://github.com/openMF/savings-plugin.git
cd savings-plugin
./mvnw clean package -Dmaven.test.skip=trueThis produces a JAR at target/savings-plugin-1.15.0-SNAPSHOT.jar.
# Create a directory for plugin JARs
mkdir -p /opt/fineract/plugins
# Copy the built plugin
cp target/savings-plugin-*.jar /opt/fineract/plugins/
# Start Fineract with the plugin on the classpath
java -Dloader.path=/opt/fineract/plugins/ -jar fineract-provider.jar# Copy the JAR into Fineract's library directory
cp target/savings-plugin-*.jar $TOMCAT_HOME/webapps/fineract-provider/WEB-INF/lib/
# Restart Tomcat
$TOMCAT_HOME/bin/shutdown.sh && $TOMCAT_HOME/bin/startup.shThe plugin auto-registers its endpoints, runs its own Liquibase migrations against every configured tenant, and is ready to use — no additional configuration needed.
docker-compose.yml runs the plugin inside Fineract on your machine. You only
need Docker with Compose 2.23.1 or later (docker compose version), about 4 GB of memory for
Docker, and internet access for the images and Maven dependencies. Java and Maven run inside a
container.
git clone https://github.com/openMF/savings-plugin.git
cd savings-plugin
docker compose up -d
sh .agents/skills/savings-docker-compose/scripts/verify-install.shIt starts PostgreSQL, builds the plugin JAR from your checkout, and starts apache/fineract:develop
with the JAR in /app/plugins. The plugin runs its own Liquibase migrations on every tenant when
Fineract starts.
With an empty Maven cache the first build downloads every dependency and takes several minutes; on
a laptop it took about 7 minutes in total. If it stops with Connect timed out, run
docker compose up -d again: finished downloads are kept in the maven-repo volume. Later builds
take under a minute, and Fineract with the plugin's migrations is up about a minute after that.
The verify script waits for Fineract and prints a PASS or FAIL line for health, the mounted JAR,
the admin login, and the plugin's /v2/offices endpoint (a Fineract without the plugin answers
404 there).
- API:
https://localhost:8443/fineract-provider/api(self-signed certificate, socurl -k), with the headerFineract-Platform-TenantId: default. Most plugin endpoints are under/v2/, a few under/v1/savings...and/v1/sinpe/.... Admin login:mifos/password. - After changing the source:
docker compose up -d --force-recreate plugin-build fineract. - Stop:
docker compose down. Delete the database too:docker compose down -v.
The fineract service sets these environment variables in docker-compose.yml (edit them there):
| Variable | Value |
|---|---|
FINERACT_HIKARI_JDBC_URL |
jdbc:postgresql://db:5432/fineract_tenants |
FINERACT_HIKARI_DRIVER_SOURCE_CLASS_NAME |
org.postgresql.Driver |
FINERACT_HIKARI_USERNAME / FINERACT_HIKARI_PASSWORD |
postgres / postgres |
FINERACT_DEFAULT_TENANTDB_HOSTNAME / FINERACT_DEFAULT_TENANTDB_PORT |
db / 5432 |
FINERACT_DEFAULT_TENANTDB_UID / FINERACT_DEFAULT_TENANTDB_PWD |
postgres / postgres |
FINERACT_DEFAULT_TENANTDB_CONN_PARAMS |
empty |
FINERACT_SERVER_SSL_ENABLED / FINERACT_SERVER_PORT |
true / 8443 |
JAVA_TOOL_OPTIONS |
-Xmx2G |
TZ |
UTC |
The db service sets POSTGRES_USER, POSTGRES_PASSWORD (both postgres) and POSTGRES_DB
(fineract_tenants), and creates the fineract_default tenant database on first start.
This is a local demo setup. The database password and the admin login are fixed defaults, and
Fineract listens on 127.0.0.1 only.
.agents/skills/savings-docker-compose/SKILL.md
is an Agent Skill that runs the Docker Compose install above, watches for
known failures, and checks the result with the verify script. It also covers stopping and
uninstalling. Run your agent from the repository root:
| Agent | Setup |
|---|---|
| Codex | None. Codex loads skills from .agents/skills/. Its default sandbox blocks Docker; allow network, for example codex exec -s workspace-write -c sandbox_workspace_write.network_access=true |
| OpenCode | None. OpenCode loads skills from .agents/skills/ |
| Pi Agent | None. Pi loads skills from .agents/skills/ once you trust the project (/trust, or pi --approve for one run) |
| Claude Code | mkdir -p .claude/skills && ln -s ../../.agents/skills/savings-docker-compose .claude/skills/ |
| Hermes Agent | hermes skills trust in the repository root; Hermes then loads skills from .agents/skills/ |
Then ask, for example: "Install the savings plugin with Docker Compose", or "Remove the savings
plugin Docker setup". The agent runs docker compose and verify-install.sh; approve those when
it asks.
The skill was tested with Claude Code, Codex (local gpt-oss:20b) and OpenCode (local
gpt-oss:20b): each installed the plugin and passed all four checks. The Pi Agent and Hermes Agent
rows follow each agent's documentation and were not run against this skill.
Pre-built snapshots are published to JFrog Artifactory:
All endpoints live under /v1/self/. Here's a summary of the available resources:
| Base Path | Resource | Methods |
|---|---|---|
/v1/self/registration |
Self-Registration & Enrollment | POST |
/v1/self/authentication |
Login (HTTP Basic) | POST |
/v1/self/password |
Forgot Password / Reset | POST |
/v1/self/user |
Current User Profile | GET, PUT |
/v1/self/userdetails |
Current User Details | GET |
/v1/self/clients |
Client Profile, Images, Charges, Transactions | GET, POST, PUT, DELETE |
/v1/self/savingsaccounts |
Savings Accounts & Transactions | GET, POST |
/v1/self/loans |
Loan Accounts, Charges, Guarantors | GET, POST, PUT |
/v1/self/shareaccounts |
Share Accounts | GET, POST |
/v1/self/accounttransfers |
Fund Transfers (Own + TPT) | GET, POST |
/v1/self/beneficiaries/tpt |
Third-Party Transfer Beneficiaries | GET, POST, PUT, DELETE |
/v1/self/loanproducts |
Loan Products Catalog | GET |
/v1/self/savingsproducts |
Savings Products Catalog | GET |
/v1/self/products/share |
Share Products Catalog | GET |
/v1/self/runreports |
Self-Service Reports | GET |
/v1/self/surveys |
Surveys (SPM) | GET |
/v1/self/surveys/scorecards |
Survey Scorecards | GET, POST |
Full OpenAPI/Swagger documentation is available at runtime via the Fineract Swagger UI when the plugin is loaded.
A Postman collection is also included for hands-on API exploration.
Interested in contributing? We'd love your help. See the Contributing Guide for everything you need — development setup, running tests, code style, and project structure.
We recommend that you Watch and Star this project on GitHub to stay up to date.
This plugin was extracted from the Apache Fineract codebase. The self-service functionality was originally part of Fineract core and was removed in this commit to keep Fineract modular. This repository continues that work as a standalone, community-maintained plugin under the Mifos Initiative.
- Mifos® is not affiliated with, endorsed by, or otherwise associated with the Apache Software Foundation® (ASF) or any of its projects.
- Apache Software Foundation® is a vendor-neutral organization; its projects are governed independently.
- Apache Fineract®, Fineract, Apache, the Apache® feather, and the Apache Fineract® project logo are either registered trademarks or trademarks of the Apache Software Foundation®.
This project is licensed under the Mozilla Public License 2.0.