MPESA Import Loan Disbursals and Loan Fees

Introduction

KEEF is planning to have mobile integration with M-PESA. They are using Mifos for their MIS platform. Mifos currently can import M-PESA loan payments and savings deposits into Mifos. To complete this integration, the ability to disburse loans will be added. This requires the following:

1. Ability to extract pre-approved loans (phone number and net disbursement amount) from Mifos. This extract will be uploaded into the M-PESA system. Once uploaded, M-PESA will disburse the loans to the clients' M-PESA accounts via mobile.

   1. Ability to diburse net disbursal loan amount. The Mifos extract should include the net loan amount, which is defined us total loan amount less loan fees due at disbursement.

2. Ability to import M-PESA disbursement transactions into Mifos.

   1. Ability to match the M-PESA disbursement records into Mifos approved loans and corresponding fees. In the given example, there will be 1 M-PESA transaction matching 2 transactions with Mifos: the Loan for 450,000 and the up-front loan fee of 3,000.  MPESA Disbursement transction of 47,000 will be equivalent to Mifos 2 transactions of 1) 50,000 disbursement and 3,000 loan fee.

User Stories

Goals

• Mifos should be able to produce an extract in CSV that contains Approved Net Loan amount and customer phone number. This extract will be used to upload loans into MPESA system for disbursal.

• Ability to import file of disbursement transactions from MPESA into Mifos to disburse the earlier approved loans.

• Ability to deduct loan fees from loan amount and generate net loan amount for export report

• Properly account for all transactions read, ignored, errored, and imported during import.

Non-Goals

The following items will not be addressed in this version of the feature:

• Ability to split loans into several transactions given the MPESA disbursal limit. The M-PESA limit has just been changed to KSH 140,000/day and KEEF disburses by checks for loan amount > KSH 50 000.

• Ability to process Client Fees

• Ability to process Loan Fees NOT due at the time of disbursement. This decision has been made with the reasoning that cashless transaction for other fees can be done by getting permission from client to withdraw funds from saving to pay for other fees. This addresses the issue that the client fees (usually around KSH 100) are to small too incure a money transfer fee (KSH 20) for the clients

• Changes to the Mifos product to restrict which fees can be associated with which product

Definitions and Terminology

• Mandatory fields will be preceded by *

• Links are italicized

• Buttons are Button |

Related Documents

[MPESA Loan Repayments and Savings Deposits Functional Spec v2|MIFOS:MPESA Loan Repayments plus Savings Deposits v2

Sample Disbursement CSV file (in Excel) (for Export)

Sample M-PESA transaction reports CSV (in Excel) (For Import)

Mifos Permissions and Mandatory Fields

Use Cases

Use Case - Account Clerk or Data Encoder tries to edit client's phone number.

Note that this is a necessity to avoid fraud. With M-PESA, money is disbursed to the clients' phone. Any user who has rights to disbuse loans through M-PESA should NOT have rights to modify a client's phone number. Otherwise, the person can disburse ALL loans to his/her personal account.  That user can VIEW the client phone number however.

Actors

• Data Encoder

• Account Clerk

Preconditions

• Only Adminstrator has permission to edit client phone number.

• Data Encoder and Account Clerk do not have permissions to edit client phone number.

Basic Flow

1. Data Encoder or Account Clerk edits a client account.  They edit the phone number field, and try to submit. 

2. Mifos displays an error message at the top that says "You do not have permission to edit the client's phone number."

Post Condition

• Users are unable to edit the Phone Number.

Use Case - Administrator tries to edit client's phone number.

Actors

• Administrator

Preconditions

Only Adminstrator has permission to edit client phone numbers

Basic Flow

1. Administrator opens a client profile.

2. Administrator edits the phone number.

3. The Administrator saves the client profile.

Post Condition

• The Administrator is able to edit and save the client phone number.

Use Case - Loan Officer(?) creates client with no phone number or national ID

Actor

• Data Encoder

• Accountant Clerk

Preconditions

• Client Phone number and Government ID have been set as mandatory fields under Define Mandatory/Hidden fields.

Basic flow

1. Loan officer creates client and does not fill in Client Phone number and/or Government ID. 

2. Loan officer tries to save client.

3. Mifos displays an error message that mandatory fields are not filled out.

Post condition

• Mifos displays error message.

Mifos Permissions Functional Requirements

Export Mifos Loan Disbursals

Export Use Cases

This feature is in the Reports section and will allow the User to export Approved Loans for disbursements.

Use Case - Administrator sets up M-PESA Disbursement Limit

Right. We should put this on Export. The current KEEF limit for disbursing via MPESA is KSH 50,000. We shouldnt export beyond this amount.

This might be out of scope if we put in Pentaho right now - we can hardcode now and then change it later?

Marie, 30Jan2011. It has been agreed that this will be hardcoded in the report right now and will then be a parameter when Pentaho is integrated into Mifos. This integration is scheduled in 2011.

Actors

• Administrator

Preconditions

Basic Flow

1. Administrator edits a properties file with new setting for the Maximum MPESA Disbursal Limit.  Administrator sets limit to 50000.

Post-conditions

• Approved loans with amount less than or equal the MPESA Disbursal Limit are included the "List of MPESA Loans" extract.

• Approved loans with loan amount > than MPESA Disbursal Limit are NOT included in the "List of MPESA Loans" extract.

Validations

• If this property is not set, then all disbursements are thrown with ERROR, Maximum Disbursement Limit NOT defined.

Use Case - Data Encoder exports Approved Normal Loans - no errors

Actors

• Data Encoder

Preconditions

• (P2) Data Encoder has permission to run "List of MPESA Loans" report in Pentaho.

• Normal Loans have been created and approved in Mifos.

Basic Flow

AT THE END OF THE DAY, at 4pm:

1. Data Encoder calls/extract report “MPESA Loan Disbursals” in Pentaho. (See attached report) Take note that this extract should deduct loan fees from disbursement amount. For each loan, net disbursement amount = loan disbursement amount – total loan fees.

2. Data Encoder selects Loan Product = Normal Loan, Group = ALL, Date = TODAY

3. This extract includes

   1. All Loans in Application Approved status.

   2. Loan Amount <= 50,000

   3. Disbursement Date = Extract Date

4. Data Encoder saves the file in CSV format.

5. Data Encoder logs into MPESA

6. While in the MPESA system, Data Encoder imports the file.

7. While in the MPESA system, Account Clerk approves the MPESA disbursement, then client receives loan amount on their phones

Post-conditions

• A report listing qualified approved loans is generated from Mifos and it should be exported and can be saved as a CSV file format

• All loan amounts reflected on the List of MPESA Loans report will be loan amounts minus loan fees.

• The extract will contain all the fields as required by MPESA system

• '“MPESA Loan Disbursals' is imported and processed in the M-PESA system.

• Clients received their loans via M-PESA.

Questions

• How do we prevent approved loans from being exported twice?  Also: there is a use case below that if there is a time-out, the loans are re-exported.  We need to think through both use cases to ensure they don’t contradict each other. * How do we stop any user from tampering with the extract*?

Validations

• Extract Summary report contains all approved loans, not exported, such as:

  • Approved loans with no phone number.

  • Approved loans with amount > 50,000.

• No bad data - ie, no numbers in columns that require text and vice versa. See FR's below.

Use Case - Data Encoder exports Approved Advance Loans - NO errors

Actors

• Data Encoder

Preconditions

• Data Encoder has permission to run "List of MPESA Loans" report.

• Advance Loans have been created and approved in Mifos.

Basic Flow

THROUGHOUT THE DAY, IMMEDIATELY after Advance Loans have been created and approved for a group.

1. Data Encoder calls/extract report “MPESA Loan Disbursals” in Pentaho. (See attached report) Take note that this extract should deduct loan fees from disbursement amount. For each loan, net disbursement amount = loan disbursement amount – total loan fees.

2. Data Encoder enters the Group for which Advance Loans are to be disbursed, and selects Advance Loan Loan product.

3. This extract should include:

   1. All Loans in Application Approved status.

   2. Loan Amount <= 50,000

   3. Disbursal Date = Extract Date

   4. Only clients in the group specified by the Data Encoder

4. Data Encoder saves the file in a CSV format.

5. Data Encoder logs onto MPESA

6. While in the MPESA system, Data Encoder imports the file.

7. While in the MPESA system, Account Clerk approves the MPESA disbursement, then client receives loan amount on their phones

Post-conditions

• A report listing qualified approved loans is generated from Mifos and it should be exported and saved as an CSV file format

• All loan amounts reflected on the List of MPESA Loans report will be less the loan fees.

• The extract will contain all the fields as required by MPESA system

• 'List of MPESA loans' is imported and procesed in the M-PESA system.

• Clients received their loans via M-PESA.

Validations

• List all approved loans, not exported, such as:

  • Approved loans with no phone number.

  • Approved loans with amount > 50,000.

• No bad data - ie, no numbers in columns that require text and vice versa. See FR's below.

Export Mifos Loan Disbursals Functional Requirements

M-PESA Loan Disbursals Export Columns and Description

Import Loan Disbursal and Fee Transactions

Use Case - Data Encoder import transaction file from MPESA

Actors:

• Data Encoder

• Accountant Clerk

Preconditions

• Data Encoder has permission to import transactions

• Data Encoder has file in xls to import

Basic Flow

1. Data encoder logs onto Mifos and navigates to the Admin section. Data Encoder selects import transactions

2. Mifos displays new screen for import transactions

3. Data Encoder selects M-PESA for Import format, and selects file from their computer for import. Accountant clicks on Continue. Take note that this is the same file used in importing Repayments and Savings Deposits.

4. Mifos imports file and checks for any errors. If there are no errors, Mifos displays Review and Submit screen with “There are no errors found. Click Submit to continue with import”

5. Data Encoder clicks on SUBMIT. Mifos displays confirmation screen that import was successful.

Post conditions

• All approved loans in Mifos will be disbursed in Mifos.

• Each approved loan is disbursed and corresponding loan fees applied. The disbursement transaction and loan fee applications are tied to 1 receipt ID.

• All loans with status "Application Pending Status" will not change.  So there needs to be a check on the loan status right? YES. Again, KEEF will use this for validation later.

• Repayments and savings deposits are processed as stated in Repayment and Savings Import functional specifications.

Validations

• If there are no approved loans found in Mifos, each row that is not an approved loan will show an error message (see below)

• See Import File Details and Validations (M-PESA) for specific column validations.

Alternative Flows

Use Case - Data Encoder Cancels import

1. At step 4, Data Encoder clicks on CANCEL instead, Mifos returns user to admin section

Post Conditions

• No data has been imported

Use Case - Import has errors and Data Encoder chooses to continue

1. At step 4, Mifos determines there are errors from Validations mentioned below. Mifos displays Review & Submit screen with error messages depending on types of error.

2. Data Clerk saves the error log.

3. Data Clerk chooses to continue with import of the valid rows and clicks on Submit. Mifos displays confirmation screen that import was successful.

Post-conditions

• Valid rows are imported and invalid rows are rejected.