Update Repayment

Endpoint

PUT /api/repayments/:id

Update an existing repayment record. This endpoint allows modifying payment details such as method, reference, and notes. Changing the payment amount requires Admin privileges and triggers automatic recalculation of payment allocations.

Authentication

Requires authentication with Bearer token.

Access Control

Admin: Can update any repayment, including amount changes
Supervisor: Can update repayments in their unions (except amount changes), within 24 hours of creation
Credit Officer: Cannot update repayments

Path Parameters

string

required

The unique identifier of the repayment to update

Request Body

amount

number

New payment amount. Admin only. Changing the amount will:

Reverse the original allocations
Delete existing allocation records
Reallocate the new amount to schedule items
Recalculate the remaining schedule
Update the loan status if needed

method

string

Update the 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

reference

string

Update the payment reference number or transaction ID

notes

string

Update notes about the payment

Time Restrictions

For non-Admin users, repayments can only be updated within 24 hours of creation. After 24 hours, only Admins can make updates.

Response

success

boolean

Indicates if the update was successful

message

string

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

data

object

The updated repayment object

string

Unique identifier for the repayment record

loanId

string

ID of the loan this repayment is for

amount

number

Updated payment amount

currencyCode

string

default:"NGN"

Currency code for the payment

paidAt

string

Date and time when payment was made (ISO 8601)

method

string

Updated payment method (CASH, TRANSFER, POS, MOBILE, USSD, OTHER)

reference

string

Updated payment reference number or transaction ID

notes

string

Updated notes about the payment

receivedByUserId

string

ID of the user who originally recorded this repayment (unchanged)

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 (may have changed if amount was updated)

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 originally recorded the repayment

string

User ID

string

User email

role

string

User role (ADMIN, SUPERVISOR, CREDIT_OFFICER)

createdAt

string

Timestamp when repayment record was originally created (unchanged)

updatedAt

string

Timestamp when repayment record was last updated

Example Request - Update Method and Reference

curl -X PUT 'https://api.example.com/api/repayments/cm123abc' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "method": "TRANSFER",
    "reference": "TXN-987654321",
    "notes": "Updated: Payment was via bank transfer, not cash"
  }'

Example Response

{
  "success": true,
  "message": "Repayment updated successfully",
  "data": {
    "id": "cm123abc",
    "loanId": "ln456def",
    "amount": 5000,
    "currencyCode": "NGN",
    "paidAt": "2024-01-15T10:30:00.000Z",
    "method": "TRANSFER",
    "reference": "TXN-987654321",
    "notes": "Updated: Payment was via bank transfer, not cash",
    "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-15T14:45:00.000Z"
  }
}

Example Request - Update Amount (Admin Only)

curl -X PUT 'https://api.example.com/api/repayments/cm123abc' \
  -H 'Authorization: Bearer ADMIN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 4500,
    "notes": "Corrected: Amount was ₦4,500 not ₦5,000"
  }'

When updating the amount, the system will:

Reverse all existing allocations to schedule items
Delete the old allocation records
Create new allocations with the corrected amount
Recalculate all remaining schedule items
Update the loan status if the change affects completion status

Amount Update Process

When an Admin changes the repayment amount:

Step 1: Reverse Original Allocations

The system finds all allocations for this repayment and reverses them:

Updates schedule items by subtracting the allocated amounts from paidAmount
Recalculates schedule item statuses (PAID → PARTIAL or PENDING)
Clears closedAt timestamps

Step 2: Delete Old Allocations

All RepaymentAllocation records for this repayment are deleted.

Step 3: Reallocate with New Amount

The new amount is allocated to schedule items following the same rules as creating a new repayment:

Sequential allocation by due date (oldest first)
Handles partial and excess payments
Creates new allocation records

Step 4: Recalculate Schedule

All remaining schedule items are recalculated to ensure consistency.

Step 5: Update Loan Status

If the amount change affects the total amount repaid, the loan status may transition:

If loan becomes fully paid → COMPLETED
If loan was completed but now has balance → ACTIVE

Common Use Cases

Correcting Payment Method

If a payment was recorded with the wrong method:

{
  "method": "MOBILE",
  "notes": "Correction: Payment was via mobile money"
}

Adding Transaction Reference

If the reference was initially missing:

{
  "reference": "REF-2024-001234"
}

Correcting Amount (Admin)

If the payment amount was recorded incorrectly:

{
  "amount": 4750,
  "notes": "Corrected amount after verification with borrower"
}

Error Responses

400

object

Bad request - validation errors

{
  "success": false,
  "message": "Repayment ID is required"
}

401

object

Unauthorized - missing or invalid authentication token

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

403

object

Forbidden - insufficient permissions

{
  "success": false,
  "message": "Only Administrators can modify the repayment amount"
}

Or for time restrictions:

{
  "success": false,
  "message": "Cannot update repayment after 24 hours"
}

404

object

Not found - repayment does not exist

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

Permission Summary

Field	Credit Officer	Supervisor	Admin
method	❌ Cannot update	✅ Within 24h	✅ Anytime
reference	❌ Cannot update	✅ Within 24h	✅ Anytime
notes	❌ Cannot update	✅ Within 24h	✅ Anytime
amount	❌ Cannot update	❌ Cannot update	✅ Anytime

Audit Trail

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

Action: REPAYMENT_UPDATED
Entity: Repayment
Actor: Authenticated user who updated the repayment
Before: Original repayment data
After: Updated repayment data
Timestamp: When the update was performed

Best Practices

Update promptly: If you notice an error, update the repayment within 24 hours to avoid needing Admin intervention
Add notes: Always include notes explaining why the update was made for audit purposes
Verify before updating: Double-check the new values before updating, especially for amount changes
Amount changes: Only use amount updates for genuine errors - don’t use this to reverse payments (use delete endpoint instead)

Authentication

Unions

Union Members

Loans

Repayments

Reports

Users

System

Endpoint

Authentication

Access Control

Path Parameters

Request Body

Time Restrictions

Response

Example Request - Update Method and Reference

Example Response

Example Request - Update Amount (Admin Only)

Amount Update Process

Step 1: Reverse Original Allocations

Step 2: Delete Old Allocations

Step 3: Reallocate with New Amount

Step 4: Recalculate Schedule

Step 5: Update Loan Status

Common Use Cases

Correcting Payment Method

Adding Transaction Reference

Correcting Amount (Admin)

Error Responses

Permission Summary

Audit Trail

Best Practices

Build docs developers (and LLMs) love

Authentication

Unions

Union Members

Loans

Repayments

Reports

Users

System

​Endpoint

​Authentication

​Access Control

​Path Parameters

​Request Body

​Time Restrictions

​Response

​Example Request - Update Method and Reference

​Example Response

​Example Request - Update Amount (Admin Only)

​Amount Update Process

​Step 1: Reverse Original Allocations

​Step 2: Delete Old Allocations

​Step 3: Reallocate with New Amount

​Step 4: Recalculate Schedule

​Step 5: Update Loan Status

​Common Use Cases

​Correcting Payment Method

​Adding Transaction Reference

​Correcting Amount (Admin)

​Error Responses

​Permission Summary

​Audit Trail

​Best Practices

Build docs developers (and LLMs) love

Endpoint

Authentication

Access Control

Path Parameters

Request Body

Time Restrictions

Response

Example Request - Update Method and Reference

Example Response

Example Request - Update Amount (Admin Only)

Amount Update Process

Step 1: Reverse Original Allocations

Step 2: Delete Old Allocations

Step 3: Reallocate with New Amount

Step 4: Recalculate Schedule

Step 5: Update Loan Status

Common Use Cases

Correcting Payment Method

Adding Transaction Reference

Correcting Amount (Admin)

Error Responses

Permission Summary

Audit Trail

Best Practices