Repay Loan

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

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

Getting Started

Core Flows

API Endpoints

Request Headers

Path Parameters

Request Body

Response

Code Examples

Error Responses

Common Error Scenarios

Repayment Flow

​Request Headers

​Path Parameters

​Request Body

​Response

​Code Examples

​Error Responses

​Common Error Scenarios

Repayment Flow

Request Headers

Path Parameters

Request Body

Response

Code Examples

Error Responses

Common Error Scenarios