Skip to main content

​
Endpoint

GET /api/repayments
Retrieve a list of repayment records with optional filters for loan, date range, payment method, and receiving officer. Results are paginated and include repayment allocations showing how payments were distributed across schedule items.

​
Authentication

Requires authentication with Bearer token. All staff roles (Admin, Supervisor, Credit Officer) can access this endpoint.

​
Query Parameters

​
page
number
default:"1"
Page number for pagination
​
limit
number
default:"20"
Number of records per page (max 100)
​
loanId
string
Filter repayments for a specific loan by loan ID
​
receivedByUserId
string
Filter repayments received by a specific user/officer
​
method
string
Filter by payment method. Options:
  • CASH - Cash payment
  • TRANSFER - Bank transfer
  • POS - Point of sale terminal
  • MOBILE - Mobile money (e.g., M-Pesa)
  • USSD - USSD payment
  • OTHER - Other payment methods
​
dateFrom
string
Filter repayments from this date (ISO 8601 format: YYYY-MM-DD)
​
dateTo
string
Filter repayments up to this date (ISO 8601 format: YYYY-MM-DD)

​
Role-Based Access

  • Admin: Can view all repayments across the system
  • Supervisor: Can view all repayments across all unions
  • Credit Officer: Can only view repayments for loans in their assigned unions

​
Response

​
success
boolean
Indicates if the request was successful
​
message
string
Response message (e.g., “Repayments retrieved successfully”)
​
data
array
Array of repayment objects
​
id
string
Unique identifier for the repayment record
​
loanId
string
ID of the loan this repayment is for
​
amount
number
Payment amount received
​
currencyCode
string
default:"NGN"
Currency code for the payment
​
paidAt
string
Date and time when payment was made (ISO 8601)
​
method
string
Payment method used (CASH, TRANSFER, POS, MOBILE, USSD, OTHER)
​
reference
string
Optional payment reference number or transaction ID
​
notes
string
Optional notes about the payment
​
receivedByUserId
string
ID of the user who recorded this repayment
​
loan
object
Basic loan information
​
id
string
Loan ID
​
loanNumber
string
Unique loan number
​
unionId
string
ID of the union this loan belongs to
​
unionMember
object
Union member (borrower) details
​
id
string
Member ID
​
code
string
Member code
​
firstName
string
Member’s first name
​
lastName
string
Member’s last name
​
receivedBy
object
Officer who recorded the repayment
​
id
string
User ID
​
email
string
User email
​
role
string
User role (ADMIN, SUPERVISOR, CREDIT_OFFICER)
​
allocations
array
Array showing how this payment was allocated to repayment schedule items
​
id
string
Allocation ID
​
amount
number
Amount allocated to this schedule item
​
scheduleItem
object
Repayment schedule item that received this allocation
​
id
string
Schedule item ID
​
sequence
number
Installment number (1, 2, 3, etc.)
​
dueDate
string
Due date for this installment
​
createdAt
string
Timestamp when repayment record was created
​
updatedAt
string
Timestamp when repayment record was last updated
​
pagination
object
Pagination information
​
page
number
Current page number
​
limit
number
Records per page
​
total
number
Total number of repayments matching the filters
​
totalPages
number
Total number of pages

​
Example Request

curl -X GET 'https://api.example.com/api/repayments?page=1&limit=20&method=CASH&dateFrom=2024-01-01&dateTo=2024-01-31' \
  -H 'Authorization: Bearer YOUR_TOKEN'

​
Example Response

{
  "success": true,
  "message": "Repayments retrieved successfully",
  "data": [
    {
      "id": "cm123abc",
      "loanId": "ln456def",
      "amount": 5000,
      "currencyCode": "NGN",
      "paidAt": "2024-01-15T10:30:00.000Z",
      "method": "CASH",
      "reference": "RCP-2024-001",
      "notes": "Payment received at branch office",
      "receivedByUserId": "usr789ghi",
      "loan": {
        "id": "ln456def",
        "loanNumber": "LN-2024-0123",
        "unionId": "un001xyz",
        "unionMember": {
          "id": "mem001",
          "code": "M-001",
          "firstName": "John",
          "lastName": "Doe"
        }
      },
      "receivedBy": {
        "id": "usr789ghi",
        "email": "[email protected]",
        "role": "CREDIT_OFFICER"
      },
      "allocations": [
        {
          "id": "alloc001",
          "amount": 3000,
          "scheduleItem": {
            "id": "sch001",
            "sequence": 1,
            "dueDate": "2024-01-10T00:00:00.000Z"
          }
        },
        {
          "id": "alloc002",
          "amount": 2000,
          "scheduleItem": {
            "id": "sch002",
            "sequence": 2,
            "dueDate": "2024-02-10T00:00:00.000Z"
          }
        }
      ],
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}

​
Payment Allocation

When a repayment is recorded, the system automatically allocates the payment to pending repayment schedule items:
  1. Sequential Allocation: Payments are allocated to schedule items in order of their due dates (oldest first)
  2. Partial Payments: If the payment amount is less than what’s due, it’s recorded as a partial payment and the schedule item status becomes PARTIAL
  3. Excess Payments: If the payment exceeds what’s due for the current item, the remaining amount is applied to the next pending items
  4. Allocations Array: The allocations field shows exactly how each payment was distributed across schedule items

​
Error Responses

​
400
object
Bad request - invalid query parameters
{
  "success": false,
  "message": "Invalid date format for dateFrom"
}
​
401
object
Unauthorized - missing or invalid authentication token
{
  "success": false,
  "message": "Authentication required"
}
​
403
object
Forbidden - insufficient permissions
{
  "success": false,
  "message": "You do not have permission to view these repayments"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us