Skip to content

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

5 watching

Forks

Latest commit

 

History

429 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Mifos® Self Service Plugin for Apache Fineract®

Java CI License: MPL 2.0 Java 25 Spring Boot 4 Fineract 1.16.0-SNAPSHOT

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.


Table of Contents


What Is This?

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.

What Does It Do?

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).

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                   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

Prerequisites

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.

Getting Started

Build from Source

git clone https://github.com/openMF/savings-plugin.git
cd savings-plugin
./mvnw clean package -Dmaven.test.skip=true

This produces a JAR at target/savings-plugin-1.15.0-SNAPSHOT.jar.

Deploy with Fineract (Docker)

# 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

Deploy with Fineract (Tomcat)

# 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.sh

The plugin auto-registers its endpoints, runs its own Liquibase migrations against every configured tenant, and is ready to use — no additional configuration needed.

Run with Docker Compose

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.sh

It 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, so curl -k), with the header Fineract-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.

Install with an AI agent

.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 JARs

Pre-built snapshots are published to JFrog Artifactory:

👉 Download latest JAR

API Reference

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.

Contributing

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.

History

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.

Important Notices

  • 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®.

License

This project is licensed under the Mozilla Public License 2.0.

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

5 watching

Forks

Releases

Packages

Used by

Contributors

Languages