Skip to content

Collection Sheets ​

Collection sheets are bulk repayment tools for group-based lending. Instead of processing each loan repayment individually, a collection sheet gathers the repayments due on members' group (JLG) loans in a group or center, plus their savings deposits due, on the meeting date into a single submission. Loans held by the group itself and members' individual loans are not on it. This is the standard workflow for MFIs with group lending programs.


Types of Collection Sheets ​

Productive Collection Sheet ​

Built for a loan officer and a meeting date. Fineract lists the centers that meet on that date and contain at least one group run by that officer; you then generate each center's sheet, which covers every group in the center. Groups that are not in a center are not included.

Standard Collection Sheet ​

Generated for a specific group or center meeting on a particular date. Does not require a staff assignment.

Individual Collection Sheet ​

Handles repayments for individual (non-group) loan accounts on a specific date.


Prerequisites ​

Collection sheets require:

  1. Groups or centers must be created with a meeting schedule (recurrence rule) attached
  2. Clients must be members of the group
  3. Loans must be active and disbursed
  4. The collection sheet date should be a scheduled meeting date. Fineract rejects other dates when it generates a group's sheet; it does not check the date when it generates a center's sheet

To create a group meeting schedule, attach a collection calendar to the group:

bash
POST /fineract-provider/api/v1/groups/{groupId}/calendars
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json
json
{
  "title": "Sunrise Group meetings",
  "typeId": 1,
  "startDate": "01 March 2025",
  "repeating": true,
  "frequency": 2,
  "interval": 2,
  "repeatsOnDay": 6,
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

typeId: 1 = collection calendar, which must repeat. frequency: 1=daily, 2=weekly, 3=monthly, 4=yearly. interval: every N periods. repeatsOnDay: day of week for weekly schedules (1=Monday, 2=Tuesday..., 7=Sunday). This example meets every second Saturday from 1 March 2025. For a center, post to /fineract-provider/api/v1/centers/{centerId}/calendars; groups inside a center follow the center's schedule.


Retrieving a Collection Sheet ​

Productive Collection Sheet (by staff) ​

First list the centers where a loan officer's groups meet on that date:

bash
GET /fineract-provider/api/v1/centers?officeId=1&staffId=3&meetingDate=2025-03-15&dateFormat=yyyy-MM-dd&locale=en

officeId and meetingDate switch this endpoint to the meeting-date listing, and staffId is required. The response lists the matching centers per loan officer in meetingFallCenters; each center's collectionMeetingCalendar.id is the calendarId to use next. Then generate each center's sheet with the center request below.

Standard Collection Sheet (by group) ​

bash
POST /fineract-provider/api/v1/groups/{groupId}?command=generateCollectionSheet
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json
json
{
  "calendarId": 12,
  "transactionDate": "15 March 2025",
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

For a center, post the same body to /fineract-provider/api/v1/centers/{centerId}?command=generateCollectionSheet. Only these four fields are accepted.


Collection Sheet Response Structure ​

The response groups clients by their group, with each client's outstanding loan amounts. Shortened here; the full response also has loanProducts, savingsProducts, attendanceTypeOptions and paymentTypeOptions:

json
{
  "dueDate": [2025, 3, 15],
  "groups": [
    {
      "groupId": 5,
      "groupName": "Sunrise Group",
      "clients": [
        {
          "clientId": 101,
          "clientName": "Jane Doe",
          "attendanceType": {
            "id": 1,
            "code": "attendanceType.present",
            "value": "Present"
          },
          "loans": [
            {
              "loanId": 234,
              "productShortName": "GRP01",
              "principalDue": 120.00,
              "interestDue": 30.00,
              "feeDue": 0.00,
              "chargesDue": 0.00,
              "totalDue": 150.00
            }
          ]
        }
      ]
    }
  ]
}

totalDue is principal plus interest plus fees due; outstanding loan charges are reported separately in chargesDue.


Attendance Tracking ​

Each client in the collection sheet has an attendanceType (an object with id, code and value). The codes are:

CodeStatus
1Present
2Absent
3Approved
4Leave
5Late

The group and center save request accepts attendance as a clientsAttendance array of { "clientId": 101, "attendanceType": 1 } entries. In Fineract 1.16.1, though, attendance sent with a group or center save is not stored: the code that writes it only runs for collectionsheet commands, and these saves run as GROUP and CENTER commands. Record attendance with the meetings API instead: POST /fineract-provider/api/v1/centers/{centerId}/meetings (or /groups/{groupId}/meetings) with calendarId, meetingDate and clientsAttendance.

Absent clients will still have their loan repayments due - the attendance code is informational and does not automatically waive the repayment.


Submitting a Collection Sheet ​

After recording payments for the group, submit the sheet:

bash
POST /fineract-provider/api/v1/groups/{groupId}?command=saveCollectionSheet
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json
json
{
  "calendarId": 12,
  "transactionDate": "15 March 2025",
  "dateFormat": "dd MMMM yyyy",
  "locale": "en",
  "paymentTypeId": 1,
  "bulkRepaymentTransactions": [
    {
      "loanId": 234,
      "transactionAmount": 150.00
    },
    {
      "loanId": 235,
      "transactionAmount": 0
    }
  ]
}

For a center sheet, post to /fineract-provider/api/v1/centers/{centerId}?command=saveCollectionSheet. calendarId and transactionDate are required.

Setting transactionAmount: 0 for an absent client skips the repayment for that loan without failing the entire submission. The unpaid installment becomes overdue once its due date has passed.


Individual Collection Sheet ​

For processing individual (non-group) loans in bulk on a given date, first generate the sheet. officeId and staffId (the loan officer) are optional filters:

bash
POST /fineract-provider/api/v1/collectionsheet?command=generateCollectionSheet
json
{
  "transactionDate": "15 March 2025",
  "officeId": 1,
  "staffId": 3,
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

Then save it. The individual sheet takes the payment type on each line:

bash
POST /fineract-provider/api/v1/collectionsheet?command=saveCollectionSheet
json
{
  "transactionDate": "15 March 2025",
  "dateFormat": "dd MMMM yyyy",
  "locale": "en",
  "bulkRepaymentTransactions": [
    {
      "loanId": 301,
      "transactionAmount": 500.00,
      "paymentTypeId": 1
    }
  ]
}

Partial Payments ​

If a client pays less than the full amount due, submit the actual amount received:

json
{
  "loanId": 234,
  "transactionAmount": 100.00
}

Fineract records a partial repayment. The unpaid part of the installment becomes overdue once its due date has passed.


Payment Types on Collection Sheets ​

On a group or center sheet, a top-level paymentTypeId applies to every line of the submission, and any paymentTypeId on a line is then ignored. Leave the top-level one out and set paymentTypeId on each bulkRepaymentTransactions line instead when clients pay via different methods (some cash, some mobile money), so one submission covers them all. The individual sheet only takes the payment type per line.

Payment types are configured under Admin > Organization > Payment Type. See the Payment Types & Codes guide.


Viewing Collection Sheet History ​

Repayments from a submitted collection sheet are posted as ordinary loan repayments and appear in the loan transaction history for each affected loan:

bash
GET /fineract-provider/api/v1/loans/{loanId}/transactions

Each loan line with a positive transactionAmount creates a transaction of type REPAYMENT on that loan.