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/selfservice-plugin.git
cd selfservice-plugin
./mvnw clean package -Dmaven.test.skip=trueThis produces a JAR at target/selfservice-plugin-1.15.0-SNAPSHOT.jar.
# Create a directory for plugin JARs
mkdir -p /opt/fineract/plugins
# Copy the built plugin
cp target/selfservice-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/selfservice-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/selfservice-plugin.git
cd selfservice-plugin
docker compose up -d
sh .agents/skills/selfservice-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 Mifos plugins this one depends on (savings-plugin) go into
/app/plugins too; without them Fineract fails to start with a ClassNotFoundException.
With an empty Maven cache, docker compose up -d to all checks passing took 8 min 21 s on a
laptop, about 7.5 min of it the Maven build downloading dependencies. Later runs reuse the
maven-repo volume, and the build takes under a minute. 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
/v1/self/authentication endpoint.
- API:
https://localhost:8443/fineract-provider/api/v1(self-signed certificate, socurl -k), with the headerFineract-Platform-TenantId: default. 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 |
SPRING_MAIN_ALLOW_BEAN_DEFINITION_OVERRIDING |
true (the plugin replaces some Fineract beans) |
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/selfservice-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 |
|---|---|
| OpenCode | None. OpenCode loads skills from .agents/skills/ |
| Codex | None. Codex loads skills from .agents/skills/ |
| Pi Agent | None. Pi loads skills from .agents/skills/ once you trust the project |
| Claude Code | mkdir -p .claude/skills && ln -s ../../.agents/skills/selfservice-docker-compose .claude/skills/ |
| Hermes Agent | mkdir -p ~/.hermes/skills/devops && cp -r .agents/skills/selfservice-docker-compose ~/.hermes/skills/devops/ |
Then ask, for example: "Install the self service plugin with Docker Compose", or "Remove the
self service plugin Docker setup". The agent runs docker compose and verify-install.sh;
approve those when it asks.
The skill was tested with OpenCode and the local gpt-oss:20b model. The other rows use each
agent's documented skill location 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 (password change; step-up protected when enabled) | 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/stepup |
Step-up (OTP) authentication for sensitive operations | GET, POST |
/v1/self/activity |
Activity history of the logged-in user (logins, transfers, beneficiary / profile / password changes, step-up) | GET |
/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 and a Bruno collection are also included for hands-on API exploration.
Sensitive operations can require a fresh one-time code (SMS or e-mail) before they are executed, so a stolen session cannot move money or change the password (US-E12-02). It is disabled by default: with the defaults the API behaves exactly as before.
Everything is configured per tenant in the external service SELF_SERVICE_STEP_UP (tables c_external_service / c_external_service_properties, seeded and disabled by Liquibase). Nothing is read from environment variables, so enabling it for one tenant never changes another tenant.
-
Give the tenant its own HMAC key (at least 32 characters, random). It is used to hash the OTPs. Treat it like the other external-service secrets (SMTP, SMS): only administrators should be able to read the external service configuration.
UPDATE c_external_service_properties SET value = '<long random value>' WHERE name = 'hmacSecret' AND external_service_id = (SELECT id FROM c_external_service WHERE name = 'SELF_SERVICE_STEP_UP');
Until a usable key is set (the seeded placeholder is too short on purpose), challenges are refused with
error.msg.selfservice.stepup.misconfigured. -
Turn it on for the tenant:
UPDATE c_external_service_properties SET value = 'true' WHERE name = 'enabled' AND external_service_id = (SELECT id FROM c_external_service WHERE name = 'SELF_SERVICE_STEP_UP');
Other keys of the
SELF_SERVICE_STEP_UPservice (values outside the range fall back to the default):Key Default Meaning enabledfalsemaster switch hmacSecretplaceholder key used to hash this tenant's OTPs (at least 32 characters) protectedActionsTPT_TRANSFER,CONFIRM_TRANSFER,CHANGE_PASSWORDalso available: OWN_TRANSFER(transfers between own accounts),APPROVE_SECOND_SIGNATURE(required for dual approval)channelsSMS,EMAILchannels offered to the user (the authenticator app has its own switch, see below) otpLength6(4-8)digits of the code otpTtlSeconds300(60-900)validity of a code maxAttempts5(1-10)wrong codes before the challenge is locked lockoutSeconds900how long a locked user/action must wait resendCooldownSeconds/maxResends60/3resend limits grantTtlSeconds120(30-600)validity of the token returned after verification challengeRateLimit/challengeRateWindowSeconds5/900challenges per user per window retentionDays30challenges are kept this long (audit trail) invalidateSessionsOnPasswordChangefollows enabledrevoke all sessions after a password change -
Make sure e-mail (SMTP) and/or SMS delivery works for the tenant: codes are sent through the self-service notification module (template
STEP_UP_OTP, es-MX by default, English with an EnglishAccept-Language).
The client must authenticate with the session token returned by login, not with the user name and password. The self-service API treats that token as a bearer-like credential and, for compatibility, currently carries it in the Authorization header wrapped as Basic base64(<token>) (the base64EncodedAuthenticationKey of the login response). Step-up only needs a stable identifier of the session, resolved through StepUpSessionResolver: it already also recognises Authorization: Bearer <token>, so the planned OIDC based security model only has to plug in its own resolver. user:password Basic auth has no session and is rejected (stepup.session.required).
| Step | Request |
|---|---|
| 0 | GET /v1/self/stepup/config - enabled? protected actions, channels this user can use |
| 1 | POST /v1/self/stepup/challenges { "action": "TPT_TRANSFER", "channel": "SMS", "payload": { ...the operation about to be confirmed... } } -> 201 with challengeId, maskedDestination, expiresAt, attemptsRemaining, resendAvailableAt (never the code) |
| 2 | POST /v1/self/stepup/challenges/{id}/verify { "otp": "123456" } -> 200 { "stepUpToken": "...", "expiresAt": "..." } |
| 2b | POST /v1/self/stepup/challenges/{id}/resend (cooldown and maximum apply; attempts are not reset) |
| 3 | the protected request with the header X-Step-Up-Token: <stepUpToken> |
The token works once, only for the same user, the same session, the same action and the same payload: the server recomputes the digest from the real request, so an approved code cannot execute a different transfer.
| Action | Protected request | Payload bound into the token |
|---|---|---|
TPT_TRANSFER |
POST /v1/self/accounttransfers?type=tpt |
fromAccountId, fromAccountType, toAccountId, toAccountType, transferAmount |
OWN_TRANSFER |
POST /v1/self/accounttransfers |
same as above |
CONFIRM_TRANSFER |
POST /v1/self/accounttransfers/confirm |
fromAccount, fromAccountType, toAccount, toAccountType, toPhoneNumber, transferType, currencyCode, transferAmount |
CHANGE_PASSWORD |
PUT /v1/self/user |
the action only (the password is never hashed or stored); all sessions are revoked afterwards |
APPROVE_SECOND_SIGNATURE |
POST /v1/self/accounttransfers/approvals/{approvalId}?command=approve |
approvalId |
When step-up protects CONFIRM_TRANSFER, the older in-line transfer OTP is replaced: /quote no longer sends a code, /confirm expects the step-up token instead of otp, and /otp/resend answers stepup.legacy.otp.disabled.
Errors use the usual Fineract body (userMessageGlobalisationCode, defaultUserMessage, errors[]) plus machine readable fields.
Code (error.msg.selfservice.stepup.) |
HTTP | Extra fields |
|---|---|---|
required |
403 | action |
invalid (unknown, expired, used, other user/session/action/payload) |
403 | |
session.required |
403 | |
otp.invalid |
400 | attemptsRemaining |
otp.expired, disabled, action.not.protected, channel.unavailable, legacy.otp.disabled, resend.unsupported, totp.disabled, totp.not.enrolled, totp.enrollment.missing |
400 | |
totp.already.enrolled |
409 | |
locked, resend.cooldown, resend.limit, rate.limited |
429 | retryAfterSeconds (+ Retry-After header) |
misconfigured |
500 |
Browser clients served from another origin must allow the X-Step-Up-Token request header in the Fineract CORS configuration (fineract.security.cors.allowed-headers).
Step-up events (ISSUED, RESENT, VERIFIED, FAILED, LOCKED, CONSUMED, REJECTED) are published as Spring StepUpEvents and the challenge rows are kept for retentionDays, so an activity feed can consume them.
A client can pair an authenticator app (Google Authenticator, Microsoft Authenticator, Authy, 1Password...) and use the 6-digit code of the app instead of an SMS or e-mail code for the same protected actions. SMS can be intercepted (SIM swap) and costs money; the app does neither. It is disabled by default and per tenant.
All keys belong to the same external service SELF_SERVICE_STEP_UP (Liquibase 089 adds them with safe defaults). Nothing is read from environment variables.
-
Give the tenant its own key (at least 32 characters, random). It protects the secrets of this tenant: the key of the AES-256-GCM encryption of the TOTP secrets and of the hash of the recovery codes is derived from it. Treat it like the other external-service secrets (SMTP, SMS,
hmacSecret): only administrators should be able to read the external service configuration. Without a usable key (the seeded placeholder is too short on purpose) nobody can pair an app and the API answerserror.msg.selfservice.stepup.misconfigured.UPDATE c_external_service_properties SET value = '<long random value>' WHERE name = 'totpEncryptionKey' AND external_service_id = (SELECT id FROM c_external_service WHERE name = 'SELF_SERVICE_STEP_UP');
If this key is changed, the secrets already stored cannot be decrypted any more: those users have to be reset (see below) and pair again.
-
Turn it on. Step-up as a whole (
enabled) must be on too:UPDATE c_external_service_properties SET value = 'true' WHERE name = 'totpEnabled' AND external_service_id = (SELECT id FROM c_external_service WHERE name = 'SELF_SERVICE_STEP_UP');
Key Default Meaning totpEnabledfalseswitch of the authenticator. It does not depend on channelstotpEncryptionKeyplaceholder at least 32 characters, see above totpIssuerMifosname the app shows next to the account (at most 40 characters) totpWindowSteps1(0-2)30-second steps accepted either side of the current one (clock drift) totpMaxFailures5(1-10)wrong codes before the authenticator locks totpLockoutSeconds900(60-86400)how long it stays locked recoveryCodeCount10(5-20)recovery codes handed out totpExclusivetruewhile a user has an active authenticator, SMS and e-mail codes are not offered (SIM-swap protection) Digits (6), period (30 s) and SHA-1 are fixed: Google Authenticator ignores any other value, so a different setting would give codes the app can never match.
All calls need the session token, like the rest of step-up, and act on the logged-in user only (there is no user id).
| Step | Request |
|---|---|
| 1 | POST /v1/self/stepup/totp/enrollment -> 201 { "secret", "otpauthUri", "issuer", "digits", "periodSeconds" }. The secret is shown once; draw otpauthUri as a QR code in the client (never send it to a third party) and offer secret as text. Refused with 409 totp.already.enrolled while an authenticator is active. |
| 2 | a step-up challenge for MANAGE_AUTHENTICATOR over SMS or e-mail (see Flow) -> stepUpToken |
| 3 | POST /v1/self/stepup/totp/enrollment/confirm { "code": "123456" } with X-Step-Up-Token -> 200 { "recoveryCodes": [ "ABCDE-FGHJK", ... ] }. The code of the app proves it holds the secret. The recovery codes are shown once. |
GET /v1/self/stepup/totp -> { "available", "status": "NONE|PENDING|ACTIVE", "recoveryCodesRemaining", "exclusive", "confirmedAt" } |
|
POST /v1/self/stepup/totp/recovery-codes (with a step-up token) -> a new set; the old codes stop working |
|
DELETE /v1/self/stepup/totp (with a step-up token, because it is active) removes the authenticator and its recovery codes. Cancelling a pairing that was never confirmed needs no token. |
MANAGE_AUTHENTICATOR is protected whenever the authenticator is on, whatever protectedActions says: a tenant that saved its own list before this feature existed must not get an unprotected way to pair a stranger's phone. When step-up is off for the tenant nothing is checked, as for every other action.
The app is the channel TOTP of the normal challenges:
| Step | Request |
|---|---|
| 1 | POST /v1/self/stepup/challenges { "action": "...", "channel": "TOTP", "payload": {...} } -> 201. Nothing is sent or stored; there is no maskedDestination, and a resend is refused (resend.unsupported). |
| 2 | POST /v1/self/stepup/challenges/{id}/verify { "otp": "123456" }, or { "recoveryCode": "ABCDE-FGHJK" } when the phone is lost -> 200 { "stepUpToken" } |
| 3 | the protected request with X-Step-Up-Token, exactly as with an SMS code |
GET /v1/self/stepup/config lists TOTP among availableChannels for a user who paired an app, and, with totpExclusive, lists only TOTP for that user.
Rules enforced by the server:
- Replay: each 30-second step is accepted once. A code that was used (or an older step) is refused.
- Lock-out per user: wrong codes count against the authenticator, not against a challenge, so opening new challenges never resets the count. After
totpMaxFailuresit is locked (429 locked,Retry-After) fortotpLockoutSeconds, and neither the right code nor a recovery code is tried meanwhile. - Recovery codes work once, only on a TOTP challenge, and are stored only as keyed hashes. They count as wrong attempts when they are wrong, so they cannot be guessed either.
- Secrets: the TOTP secret is stored AES-256-GCM encrypted (random nonce, the user id is bound in, so a row copied to another user does not decrypt). It is never logged, never put in an event, never returned again. Anybody who can read the database and the external service properties can decrypt it: that is the same trust level as the SMTP password in the same service.
- Time: codes use Unix time, never the tenant's local date.
A member of staff removes the pairing; the user falls back to SMS or e-mail codes and can pair a new app:
DELETE /v1/selfservice/users/{userId}/totp (permission UPDATE_SELFSERVICEUSER, same office-hierarchy rule as the other user administration calls)
It answers { "removed": true|false } and works even when the tenant has switched the authenticator off. The user sees AUTHENTICATOR_RESET in the activity history; the address of the staff member is not stored there.
The history gets AUTHENTICATOR_ENROLLED, AUTHENTICATOR_REMOVED, AUTHENTICATOR_RESET, AUTHENTICATOR_LOCKED, RECOVERY_CODES_REGENERATED and RECOVERY_CODE_USED, so a user can spot an account takeover. Spring TotpEvents carry the same facts, never a code, a secret or a hash.
Not in this version: security e-mails to the user when the authenticator is paired or removed, and a "required" mode that forces every client to pair one.
A client can see the logins and sensitive actions of their own account and spot unauthorised use (US-E12-05).
GET /v1/self/activity?limit=20&offset=0&type=LOGIN,TRANSFER_CONFIRMED
- Newest first, only the logged-in user's own events. There is no user id parameter.
limitdefaults to 20 and is capped by the tenant settingmaxPageSize.typeis an optional list. The answer is{ "totalFilteredRecords": n, "pageItems": [ { "id", "type", "outcome", "occurredAt", "ipAddress", "details" } ] }.type:LOGIN,LOGIN_FAILED,LOGIN_NEW_DEVICE,LOGOUT,PASSWORD_CHANGED,PASSWORD_RESET,TRANSFER_CONFIRMED,BENEFICIARY_ADDED,BENEFICIARY_UPDATED,BENEFICIARY_DELETED,PROFILE_IMAGE_CHANGED,PROFILE_IMAGE_REMOVED,SINPE_SUBSCRIPTION_CHANGED,STEP_UP_REQUESTED,STEP_UP_VERIFIED,STEP_UP_LOCKED,AUTHENTICATOR_ENROLLED,AUTHENTICATOR_REMOVED,AUTHENTICATOR_RESET,AUTHENTICATOR_LOCKED,RECOVERY_CODES_REGENERATED,RECOVERY_CODE_USED. The client translates the code; no text is stored.- Where the address comes from: the address of the connection (
getRemoteAddr()). The plugin never readsX-Forwarded-Foritself, because any client can write anything in that header and the history exists to show where an action really came from. Behind a reverse proxy, configure the trusted proxies of the server (for exampleserver.forward-headers-strategy=nativeandserver.tomcat.remoteip.internal-proxies=<your proxies>); thengetRemoteAddr()is the real client. Without a trusted proxy the address of the proxy is shown. The same rule applies to the address kept with step-up challenges. - Privacy: the IP address is stored and returned masked (
203.0.x.x, IPv62001:db8:x:x:x:x:x:x); the full address is never kept.detailsis built from a whitelist per type (for a transfer: amount, currency when known, destination name, last 4 digits of the destination account). A password, OTP, token, e-mail, phone number or full account number never reaches the history. - A wrong-password login is recorded at most once per minute per user, so a guessing attack cannot flood the feed. Wrong step-up codes are not listed one by one; the request, the successful verification and a lock-out are.
- Recording never breaks the action it describes: a failure to write is only logged. A transfer is listed only after it was committed.
The external service SELF_SERVICE_ACTIVITY (tables c_external_service / c_external_service_properties, seeded by Liquibase). Nothing is read from environment variables.
| Key | Default | Meaning |
|---|---|---|
enabled |
true |
false stops recording (existing rows stay until purged) |
retentionDays |
90 |
how long the history is kept, 1..3650 (some regions need longer) |
maxPageSize |
100 |
largest page a client may ask for, 10..500 |
UPDATE c_external_service_properties SET value = '365'
WHERE name = 'retentionDays'
AND external_service_id = (SELECT id FROM c_external_service WHERE name = 'SELF_SERVICE_ACTIVITY');A nightly job (batch instances only, mifos.self.service.activity.purge.enabled / .cron) deletes older rows of every tenant using that tenant's own retentionDays.
A business (ENTITY) client can require a second signatory for large transfers (MX-489). It is off unless the tenant switches it on and a threshold row exists for the client, so every other tenant and client keeps the single-user flow.
- Tenant switch: service
SELF_SERVICE_DUAL_APPROVAL, propertyenabled(defaultfalse, seeded by Liquibase 087). While it isfalseno transfer is held, whatever thresholds exist. Turning it off does not cancel transfers already held: they can still be approved or rejected.
UPDATE c_external_service_properties SET value = 'true' WHERE name = 'enabled'
AND external_service_id = (SELECT id FROM c_external_service WHERE name = 'SELF_SERVICE_DUAL_APPROVAL');- Threshold: set per client and currency in
m_selfservice_client_approval_threshold. A transfer is held when its amount, excluding the fee, is greater than or equal to the threshold for the source account's currency. The currency is read from the account, not from the request. There is no tenant-wide threshold. - Signatories: self-service users who may approve for a client are listed in
m_selfservice_entity_signatory(is_active = falserevokes them). The one-owner-per-client mapping (unique_self_client) is unchanged. - Approver OTP: the tenant must have step-up enabled with
APPROVE_SECOND_SIGNATUREinprotectedActions. Otherwise a transfer that needs approval is refused (validation.msg.transferapproval.approvalId.otp.not.configured) instead of being held where nobody could approve it. - Another signatory: the client needs at least one active signatory other than the initiator. Otherwise the transfer is refused (
validation.msg.transferapproval.approvalId.no.other.signatory), because nobody could decide it.
INSERT INTO m_selfservice_client_approval_threshold (client_id, currency_code, threshold_amount)
VALUES (<entityClientId>, 'CRC', 1000000);
INSERT INTO m_selfservice_entity_signatory (client_id, appuser_id, is_active, created_at)
VALUES (<entityClientId>, <selfServiceUserId>, true, CURRENT_TIMESTAMP);| Step | Who | Request |
|---|---|---|
| 1 | initiator | the usual prepare, quote and confirm. At or above the threshold, /confirm answers { "status": "PENDING_APPROVAL", "approvalId": 5 } and no money moves |
| 2 | approver | GET /v1/self/accounttransfers/approvals lists pending transfers of the clients where they are an active signatory (canDecide is false for their own) |
| 3 | approver | step-up challenge for APPROVE_SECOND_SIGNATURE with payload: { "approvalId": 5 }, then verify |
| 4 | approver | POST /v1/self/accounttransfers/approvals/5?command=approve with X-Step-Up-Token, or ?command=reject (no OTP) |
On approval the funds are checked again and the initiator's request is executed through the normal confirm path, as the initiator. The approval is committed before any money moves, so a transfer is sent at most once: if execution fails (for example after a PIN or SINPE gateway has already accepted it), the approval ends as FAILED and can never be approved again. Reconcile it against the gateway before the initiator submits a new transfer. The initiator cannot decide on their own transfer, a non-signatory gets the same not.found error as a missing approval, and a transfer can be decided only once, even under concurrent requests. The legacy POST /v1/self/accounttransfers refuses transfers that need a second signature (dual.approval.required).
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.