Create Repayment

Endpoint

POST /api/repayments

Record a new repayment for a loan. The payment is automatically allocated to pending repayment schedule items in order of due date. This endpoint handles partial payments, excess payments, and automatically updates the loan status.

Authentication

Requires authentication with Bearer token. All staff roles (Admin, Supervisor, Credit Officer) can create repayments.

Request Body

loanId

string

required

ID of the loan this repayment is for. The loan must be in APPROVED, ACTIVE, or DEFAULTED status.

amount

number

required

Payment amount received. Must be a positive number.

method

string

required

Payment method used. 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

paidAt

string

Date and time when payment was made (ISO 8601 format). If not provided, defaults to current timestamp.

reference

string

Optional payment reference number or transaction ID (e.g., bank reference, receipt number)

notes

string

Optional notes about the payment (e.g., “Payment received at branch office”, “Partial payment - borrower will pay balance next week”)

scheduleItemId

string

Optional: Target a specific repayment schedule item for payment allocation. If provided, this schedule item will be prioritized when allocating the payment. Useful for making payments on specific overdue installments.

Automatic Payment Processing

When you create a repayment, the system automatically:

Validates the Loan: Checks that the loan exists and is in a valid status (APPROVED, ACTIVE, or DEFAULTED)
Creates the Repayment Record: Records the payment with all details
Allocates Payment to Schedule Items:
- If scheduleItemId is provided, prioritizes that schedule item
- Otherwise, allocates to pending schedule items in order of due date (oldest first)
- Handles partial payments by marking items as PARTIAL
- Applies excess payments to subsequent schedule items
Recalculates Schedule: Updates all schedule items with new paid amounts and statuses
Updates Loan Status: Automatically transitions loan status:
- APPROVED → ACTIVE (first payment received)
- ACTIVE → COMPLETED (loan fully paid)
- DEFAULTED → ACTIVE (payment received on overdue loan)

Response

success

boolean

Indicates if the repayment was recorded successfully

message

string

Response message (e.g., “Repayment recorded successfully”)

data

object

The created repayment object

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

Payment reference number or transaction ID

notes

string

Notes about the payment

receivedByUserId

string

ID of the user who recorded this repayment (from authentication token)

loan

object

Loan details with borrower information

string

Loan ID

loanNumber

string

Unique loan number

principalAmount

number

Original loan amount

status

string

Current loan status (APPROVED, ACTIVE, COMPLETED, DEFAULTED)

unionMember

object

Union member (borrower) details

string

Member ID

firstName

string

Member’s first name

lastName

string

Member’s last name

receivedBy

object

Officer who recorded the repayment

string

User ID

string

User email

role

string

User role (ADMIN, SUPERVISOR, CREDIT_OFFICER)

createdAt

string

Timestamp when repayment record was created

updatedAt

string

Timestamp when repayment record was last updated

Example Request

curl -X POST 'https://api.example.com/api/repayments' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "loanId": "ln456def",
    "amount": 5000,
    "method": "CASH",
    "reference": "RCP-2024-001",
    "notes": "Payment received at branch office"
  }'

Example Response

{
  "success": true,
  "message": "Repayment recorded 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",
      "principalAmount": 50000,
      "status": "ACTIVE",
      "unionMember": {
        "id": "mem001",
        "firstName": "John",
        "lastName": "Doe"
      }
    },
    "receivedBy": {
      "id": "usr789ghi",
      "email": "[email protected]",
      "role": "CREDIT_OFFICER"
    },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Partial Payment Example

If a borrower pays less than the full installment amount:

{
  "loanId": "ln456def",
  "amount": 2000,
  "method": "CASH",
  "notes": "Partial payment - borrower will pay balance next week"
}

The system will:

Apply ₦2,000 to the oldest pending schedule item
Mark that schedule item as PARTIAL
Track the remaining balance (₦3,000 if the installment was ₦5,000)
The next payment will complete this item before moving to the next

Excess Payment Example

If a borrower pays more than one installment:

{
  "loanId": "ln456def",
  "amount": 15000,
  "method": "BANK_TRANSFER",
  "reference": "TXN-987654321",
  "notes": "Payment for multiple installments"
}

The system will:

Apply ₦5,000 to installment 1 (mark as PAID)
Apply ₦5,000 to installment 2 (mark as PAID)
Apply ₦5,000 to installment 3 (mark as PAID)
Create allocation records showing the distribution

Targeting Specific Schedule Items

To pay a specific overdue installment (e.g., installment 3):

{
  "loanId": "ln456def",
  "amount": 5000,
  "method": "CASH",
  "scheduleItemId": "sch003",
  "notes": "Payment for installment 3 specifically"
}

The system will prioritize that schedule item when allocating the payment.

Error Responses

400

object

Bad request - validation errors

{
  "success": false,
  "message": "Amount must be positive"
}

401

object

Unauthorized - missing or invalid authentication token

{
  "success": false,
  "message": "Authentication required"
}

404

object

Not found - loan does not exist

{
  "success": false,
  "message": "Loan not found"
}

422

object

Unprocessable entity - loan in invalid status

{
  "success": false,
  "message": "Can only make payments on active, approved, or defaulted loans"
}

Audit Trail

All repayment creation actions are automatically logged to the audit trail with:

Action: REPAYMENT_CREATED
Entity: Repayment
Actor: Authenticated user who created the repayment
Timestamp: When the repayment was recorded
Metadata: Repayment details including amount, method, and loan information

Authentication

Unions

Union Members

Loans

Repayments

Reports

Users

System

Endpoint

Authentication

Request Body

Automatic Payment Processing

Response

Example Request

Example Response

Partial Payment Example

Excess Payment Example

Targeting Specific Schedule Items

Error Responses

Audit Trail

Build docs developers (and LLMs) love

Authentication

Unions

Union Members

Loans

Repayments

Reports

Users

System

​Endpoint

​Authentication

​Request Body

​Automatic Payment Processing

​Response

​Example Request

​Example Response

​Partial Payment Example

​Excess Payment Example

​Targeting Specific Schedule Items

​Error Responses

​Audit Trail

Build docs developers (and LLMs) love

Endpoint

Authentication

Request Body

Automatic Payment Processing

Response

Example Request

Example Response

Partial Payment Example

Excess Payment Example

Targeting Specific Schedule Items

Error Responses

Audit Trail