https://{your-domain}.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>"
}API Endpoints
Repay Loan
Allows customers to make a partial repayment for their loan.
POST
/
api
/
v1
/
services
/
user
/
repay-loan
/
{user-id}
https://{your-domain}.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://{your-domain}.fincode.software/api/v1/services/user/repay-loan/{user-id}
Before making a repayment, customers should:
- Get repayment instructions using
GET /repayment-instructions/{loan-application-id} - Make a bank transfer to the provided account with the repayment reference
- 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
string
required
The JWT Access Token obtained from the
/login or /refresh-token endpoint.string
required
Unique idempotency key for the request to prevent duplicate processing.
string
required
The date and time at which the request was initiated (ISO 8601 format).
string
required
The IP address of the customer making the request.
string
required
Unique identifier for the interaction/session.
string
default:"application/json"
required
Must be
application/json.Path Parameters
string
required
The unique identifier (UUID) of the user making the repayment. This must match the authenticated user.
Request Body
number
required
The amount to be repaid. Must be greater than zero and cannot exceed the total payable amount.
string
required
The unique identifier (UUID) of the customer making the repayment. Must match the authenticated user.
string
required
The unique identifier (UUID) of the loan account being repaid.
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.
string
The payment reference number from the bank transfer. This should match the reference provided in the repayment instructions.
string
The date when the payment was made (ISO 8601 format). If not provided, the current date is used.
string
Optional description or narration for the payment.
Response
Returns confirmation of the repayment submission with details.string
default:"SUCCESS"
Overall status of the API request.
object
Repayment confirmation details.
Show data object
Show data object
string
Unique identifier for the repayment record.
number
The amount that was repaid.
string
Name of the customer who made the repayment.
string
Email address of the customer.
string
Name of the loan product.
string
Payment reference number for the repayment.
string
default:"PENDING_VERIFICATION"
Status of the repayment verification. Options:
PENDING_VERIFICATION, VERIFIED, REJECTED.string
Message confirming the repayment submission.
Code Examples
curl --location --request POST 'https://{your-domain}.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"
}'
const axios = require('axios');
const BASE_URL = 'https://{your-domain}.fincode.software/api/v1/services/user';
async function repayLoan(accessToken, userId, repaymentData) {
try {
const response = await axios.post(
`${BASE_URL}/repay-loan/${userId}`,
{
repaymentAmount: repaymentData.amount,
customerId: repaymentData.customerId,
accountId: repaymentData.accountId,
bankAccountId: repaymentData.bankAccountId,
repaymentReference: repaymentData.reference,
paymentDate: repaymentData.paymentDate || new Date().toISOString(),
paymentNarration: repaymentData.narration,
},
{
headers: {
'X-Auth-Token': accessToken,
'x-idempotency-key': `key-${Date.now()}`,
'x-fapi-auth-date': new Date().toISOString(),
'x-fapi-customer-ip-address': '192.168.1.1',
'x-fapi-interaction-id': `interaction-${Date.now()}`,
'Content-Type': 'application/json',
},
}
);
const repayment = response.data.data;
console.log('Repayment submitted successfully:');
console.log(`- Repayment ID: ${repayment.id}`);
console.log(`- Amount: ${repayment.repaymentAmount}`);
console.log(`- Status: ${repayment.verificationStatus}`);
console.log(`- Message: ${repayment.message}`);
return repayment;
} catch (error) {
console.error(
'Failed to submit repayment:',
error.response?.data || error.message
);
throw error;
}
}
// Usage Example
const accessToken = 'YOUR_JWT_ACCESS_TOKEN';
const userId = '123e4567-e89b-12d3-a456-426614174000';
// First, get repayment instructions
// Then make bank transfer
// Finally, record the repayment
repayLoan(accessToken, userId, {
amount: 50000,
customerId: '123e4567-e89b-12d3-a456-426614174000',
accountId: '223e4567-e89b-12d3-a456-426614174001',
bankAccountId: '323e4567-e89b-12d3-a456-426614174002',
reference: 'REF-2024-01-15-001',
paymentDate: '2024-01-15T10:00:00Z',
narration: 'Monthly installment payment',
});
Error Responses
string
default:"FAILED"
Status will be
FAILED if an error occurs.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