View Source

Target release	16.xx
Epic	MIFOSX-2294
Document status
Document owner
Designer	Community Team
Developers	Lead developer
QA	Lead tester

Overview

Mifos X is being sought out by financial co-operative organizations (non-credit union/SACCO) as a solution to support their financial service offerings AND to pay stake holders dividends on their investments.

Background and strategic fit

Strategic vision of The Mifos Initiative to support financial cooperatives.

Requirements/User Stories

#	Title	User Story	Importance
1	Manage products for Share accounts	As an operations manager, I wish to define a deposit product that will be used to maintain member shares, balances and dividends paid to members	Must Have
2	Create share account for member	As operations staff, I wish to create a share account for the member.	Must Have
3	Apply for additional shares for member	Stake holders (share holders) have the option to purchase additional shares	Must Have
4	Allow Recurring Deposits as share	Share holders may allow a regular recurring deposit transferred from their savings account into a share account	Should
4	Calculate dividends based on average daily balance	Dividends should be calculated based on average daily balance to parity in payment	Must Have
6	Manage configurations for dividend calculations		Must Have
7	Pre-View Calculated Dividend		Must Have
8	Approve and Post Calculated Dividend		Must Have

Business Rules

Share accounts will be deposit accounts. There will be no interest rate that is associated to the shares account.

At the time of applying for the share account, the purchase price (unit price and number of shares must be captured) and any fees will be collected from client. The fee will be an income whereas the purchase price will be held in a suspense account (liability).

Once the application is approved, the amount will move from a suspense account to the liability account.

If application is rejected, the amount is repaid from the suspense account.

A member may purchase additional shares which will follow the same process.

Attributes

Attribute	Description	Notes
Number of shares
Value of shares

Share Product Attributes

While creating a shares product, we need to capture the following attributes

Product Name, Short Name, Description, Currency, decimal places, multiples of, Total number of shares, Total shares to be issued, Unit/Nominal Price, Total Share Capital (system will auto calculates), Suspense account,Equity account, Total number of shares to be allotted per client (min, default, max), Market Price (Date, Value), Charges applicable, Calculate Dividend for members who are no longer active (yes/no), Lock in Period (in Days, Weeks, Months, Years), Minimum active period For dividends (in days/weeks/months/years)

Share Account Attributes

While creating a share account, we need to capture the following attributes

Client Id, Share product Id, Submitted On, Approved On, Field Officer, External Id, Currency, Decimal Places, Currency Multiples of, Number of shares [date, number, Market Price], Suspense Account, Equity Account, Link Savings Account number for Dividends, Lock In Period, Minimum Active Period, Calculate Dividend for members who are no longer active (yes/no), Charges (Purchase Charges, Redeem Charges)

Security and Permissions

New permissions needed for the following:

Create / List / View / Edit Share products
Create / View / Edit Share accounts
Apply for Shares
Post Dividend
Manage Configurations for Dividend Calculation
Pre-View Calculated Dividend
Approve and Post Calculated Dividend

Mifos Functionality Enhancements

New Screens

Share Products:

Listing
New/Create
Edit

Share Accounts:

All screens similar to Savings account except the following
Deposit --> to be changed to --> Purchase shares
Withdraw --> to be changed to --> Redeem shares
Transfer funds --> to be changed to --> Transfer shares

All transactions to have share reference, number of shares and value of shares

Changes to Existing Screens

Option to create new Share Products from Admin screens

Option to create new Shares account from member screens

Changes/Enhancements to Batch Jobs

A new batch job is needed (which will always be invoked manually) to compute dividends based on average share account balances.

Dividends will be calculated based on the following configurations which may be captured and stored for each period where calculations are to be done:

a) Calculate Dividend for members who are no longer active (True/False)

b) Minimum active period (in days/weeks/months) for member to be eligible for dividend (Numeric + period type)

c) Amount to be distributed or percentage of profits to be distributed

d) Dividend to be calculated based on (Daily balances, monthly balances etc)

e) Balance to be considered between (Two dates)

Changes/Enhancements to Accounting Entries

Additional account heads to be captured (similar to Savings accounts):

Suspense account for share application money

User interaction and design

Include any mockups, diagrams or visual designs relating to these requirements.

Exception Handling

List of error scenarios and the action - if message is to be displayed, then text of the message.

Reporting

List of changes/enhancements/new reports to support this functionality

APIs

API to link loan modules to Shares module ( also modify savings products to have this API linkage) for automatic management of Compulsory Savings needed for Loan proceeds. e.g 20,000 loan may require one to have 3 shares and 15% loan amount as compulsory savings, 45,000 loan may require 5 shares and 15% loan amount as compulsory savings and this should be a loan checker hence if condition is not met then loan proceeds fails.

From a functional perspective, list of existing APIs that need changes.

Product Level API(s)

List all Share Products

Request Method: GET
https://server:port/mifosng-provider/api/v1/shareproducts

Get Share Product Details

Request Method: GET
https://server:port/mifosng-provider/api/v1/shareproducts/{shareProductId}?template=true

Preview of the Dividend Calculation for Individual Accounts

Request Method: GET
https://server:port/mifosng-provider/api/v1/shareproducts/{shareProductId}?command=previewdividends

Template for Share Product Creation

Request Method: GET
https://server:port/mifosng-provider/api/v1/shareproducts/template

Modify Share Product

Request Method: PUT
https://server:port/mifosng-provider/api/v1/shareproducts/{shareProductId}

Create a Share Product

Request Method: POST
https://server:port/mifosng-provider/api/v1/shareproducts

Post Dividends to Individual Accounts

Request Method: POST
https://server:port/mifosng-provider/api/v1/shareproducts/{shareProductId}?command=giveoutdividends

Account Level API(s)

Template(s) for Share Account Creation

Request Method: GET
https://server:port/mifosng-provider/api/v1/shareaccounts/template?clientId={clientId}&staffInSelectedOfficeOnly=true
https://server:port/mifosng-provider/api/v1/shareaccounts/template?clientId={clientId}&productId={shareProductId}&staffInSelectedOfficeOnly=true

Retrieve All Client Accounts (including share accounts)

Request Method: GET
https://server:port/mifosng-provider/api/v1/clients/{clientId}/accounts

Retrieve Share Account Details

Request Method: GET
https://server:port/mifosng-provider/api/v1/shareaccounts/{shareAccountId}?associations=all

Create Share Account

Request Method: POST
https://server:port/mifosng-provider/api/v1/shareaccounts

Update Share Account

Request Method: PUT
https://server:port/mifosng-provider/api/v1/shareaccounts/{shareAccountId}

Approve Share Account

Request Method: POST
https://server:port/mifosng-provider/api/v1/shareaccounts/{shareAccountId}?command=approve

Apply for Additional Shares

Request Method: POST
https://server:port/mifosng-provider/api/v1/shareaccounts/{shareAccountId}?command=applyadditionalshares

Approve Additional Shares request

Request Method: POST
https://server:port/mifosng-provider/api/v1/shareaccounts/{shareAccountId}?command=approveadditionalshares

Notes

Points to be handled during upgrades

Any reference data that needs to be prepopulated or defaulted for clients/users

Questions

Below is a list of questions to be addressed as a result of this requirements document:

Question	Outcome
(e.g. How we make users more aware of this feature?)	Communicate the decision reached

Out of Scope

List the features discussed which are out of scope or might be revisited in a later release.