Finecko Documentation

Appearance

Collection Sheets ​

Collection sheets are bulk repayment tools for group-based lending. Instead of processing each loan repayment individually, a collection sheet aggregates all repayments due from a group or center on their meeting date into a single submission. This is the standard workflow for MFIs with group lending programs.

Types of Collection Sheets ​

Productive Collection Sheet ​

Generated for a loan officer across all groups and centers they manage that share the same meeting date. Covers all clients in all of that officer's groups meeting on the specified date.

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 must be a scheduled meeting date for the group

To create a group meeting schedule:

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

frequency: 1=daily, 2=weekly, 3=monthly, 4=yearly. interval: every N periods. repeatsOnDay: day of week (1=Monday, 2=Tuesday..., 7=Sunday).

Retrieving a Collection Sheet ​

Productive Collection Sheet (by staff) ​

bash
GET /fineract-provider/api/v1/collectionsheet?calendarId={calendarId}&dueDate={date}&tenantIdentifier=default

Or via the search endpoint:

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

Standard Collection Sheet (by group) ​

bash
POST /fineract-provider/api/v1/groups/{groupId}/generateCollectionSheet
json
{
  "calendarId": 12,
  "dueDate": "15 March 2025",
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

Collection Sheet Response Structure ​

The response groups clients by their group, with each client's outstanding loan amounts:

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

Attendance Tracking ​

Each client in the collection sheet has an attendanceType. Record attendance as part of the submission:

CodeStatus
1Present
2Absent
3Late
4On leave
5Approved absence

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

Submitting a Collection Sheet ​

After recording payments and attendance for the group, submit the sheet:

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

Setting transactionAmount: 0 for an absent client skips the repayment for that loan without failing the entire submission. The loan will show as overdue after COB runs.

Individual Collection Sheet ​

For processing individual (non-group) loans in bulk on a given date:

bash
POST /fineract-provider/api/v1/individualloanaccounts/savecollectionsheet
json
{
  "dueDate": "15 March 2025",
  "dateFormat": "dd MMMM yyyy",
  "locale": "en",
  "bulkRepaymentTransaction": {
    "transactionDate": "15 March 2025",
    "paymentTypeId": 1
  },
  "clients": [
    {
      "clientId": 110,
      "loans": [
        {
          "loanId": 301,
          "transactionAmount": 500.00
        }
      ]
    }
  ]
}

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 remaining balance becomes overdue if unpaid by the next COB run.

Payment Types on Collection Sheets ​

The paymentTypeId on bulkRepaymentTransaction applies to the whole sheet submission. If clients pay via different methods (some cash, some mobile money), you have two options:

  1. Submit the sheet in multiple passes, one per payment type
  2. Record individual repayments manually for clients with different payment methods, then submit the rest as a bulk sheet

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

Viewing Collection Sheet History ​

Submitted collection sheets are recorded as batch transactions and appear in the loan transaction history for each affected loan:

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

Each collection sheet submission creates a transaction of type REPAYMENT on the loan.