Skip to main content
POST
/
api
/
v1
/
services
/
user
/
repay-loan
/
{user-id}
[https://finlend.fincode.software/api/v1/services/user/repay-loan/{user-id}](https://finlend.fincode.software/api/v1/services/user/repay-loan/{user-id})

{
  "status": "<string>",
  "data": {
    "id": "<string>",
    "repaymentAmount": 123,
    "customerName": "<string>",
    "email": "<string>",
    "loanProductName": "<string>",
    "repaymentReference": "<string>",
    "verificationStatus": "<string>",
    "message": "<string>"
  },
  "message": "<string>"
}
Customers can use this endpoint to record a partial repayment for their loan. This is typically used after making a bank transfer to the repayment account. 
[https://finlend.fincode.software/api/v1/services/user/repay-loan/{user-id}](https://finlend.fincode.software/api/v1/services/user/repay-loan/{user-id})
Before making a repayment, customers should:
  1. Get repayment instructions using GET /repayment-instructions/{loan-application-id}
  2. Make a bank transfer to the provided account with the repayment reference
  3. Record the repayment using this endpoint
Some loans use third-party collection services. Manual repayments via this API may not be allowed for such loans. The system will return an error if manual repayment is not permitted.

​
Request Headers

​
X-Auth-Token
string
required
The JWT Access Token obtained from the /login or /refresh-token endpoint.
​
x-idempotency-key
string
required
Unique idempotency key for the request to prevent duplicate processing.
​
x-fapi-auth-date
string
required
The date and time at which the request was initiated (ISO 8601 format).
​
x-fapi-customer-ip-address
string
required
The IP address of the customer making the request.
​
x-fapi-interaction-id
string
required
Unique identifier for the interaction/session.
​
Content-Type
string
default:"application/json"
required
Must be application/json.

​
Path Parameters

​
user-id
string
required
The unique identifier (UUID) of the user making the repayment. This must match the authenticated user.

​
Request Body

​
repaymentAmount
number
required
The amount to be repaid. Must be greater than zero and cannot exceed the total payable amount.
​
customerId
string
required
The unique identifier (UUID) of the customer making the repayment. Must match the authenticated user.
​
accountId
string
required
The unique identifier (UUID) of the loan account being repaid.
​
bankAccountId
string
required
The unique identifier (UUID) of the bank account from which the payment was made. This must be a bank account that belongs to the customer.
​
repaymentReference
string
The payment reference number from the bank transfer. This should match the reference provided in the repayment instructions.
​
paymentDate
string
The date when the payment was made (ISO 8601 format). If not provided, the current date is used.
​
paymentNarration
string
Optional description or narration for the payment.

​
Response

Returns confirmation of the repayment submission with details.
​
status
string
default:"SUCCESS"
Overall status of the API request.
​
data
object
Repayment confirmation details.

​
Code Examples

curl --location --request POST 'https://finlend.fincode.software/api/v1/services/user/repay-loan/123e4567-e89b-12d3-a456-426614174000' \
--header 'X-Auth-Token: YOUR_JWT_ACCESS_TOKEN' \
--header 'x-idempotency-key: unique-key-12345' \
--header 'x-fapi-auth-date: 2024-01-15T10:30:00Z' \
--header 'x-fapi-customer-ip-address: 192.168.1.1' \
--header 'x-fapi-interaction-id: interaction-12345' \
--header 'Content-Type: application/json' \
--data '{
    "repaymentAmount": 50000,
    "customerId": "123e4567-e89b-12d3-a456-426614174000",
    "accountId": "223e4567-e89b-12d3-a456-426614174001",
    "bankAccountId": "323e4567-e89b-12d3-a456-426614174002",
    "repaymentReference": "REF-2024-01-15-001",
    "paymentDate": "2024-01-15T10:00:00Z",
    "paymentNarration": "Monthly installment payment"
}'

​
Error Responses

​
status
string
default:"FAILED"
Status will be FAILED if an error occurs.
​
message
string
Error message describing what went wrong.

​
Common Error Scenarios

  • Loan Not Found: No active loan found for the provided customer ID
  • Loan Closed: The loan is already closed and cannot be repaid
  • Unauthorized: The customer ID does not match the authenticated user
  • Manual Repayment Not Allowed: The loan uses third-party collection and manual repayments are not permitted
  • Invalid Amount: Repayment amount is zero, negative, or exceeds total payable
  • Bank Account Mismatch: The bank account does not belong to the customer
  • Missing Loan Application: Loan application ID is missing for the customer loan record

Repayment Flow

See the complete repayment flow documentation