Build a Microfinance Repayment Portal

Tables: borrowers (name, phone, id_number, bank_code, account_number, paystack_recipient_code, credit_score), loans (borrower_id, principal, interest_rate, term_weeks, weekly_installment, status, disbursed_at), repayments (loan_id, installment_number, due_date, amount_due, amount_paid, status, paystack_ref, paid_at).

function calculateInstallment(principal, interestRate, termWeeks) {
  var totalInterest = principal * interestRate;
  var total = principal + totalInterest;
  return Math.ceil(total / termWeeks);
}

async function disburseLoan(loanId) {
  var loan = await db.loans.findById(loanId);
  var borrower = await db.borrowers.findById(loan.borrower_id);

  // Ensure recipient code exists
  if (!borrower.paystack_recipient_code) {
    var rcpRes = await fetch('https://api.paystack.co/transferrecipient', {
      method: 'POST',
      headers: { Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY, 'Content-Type': 'application/json' },
      body: JSON.stringify({ type: 'nuban', name: borrower.name, account_number: borrower.account_number, bank_code: borrower.bank_code, currency: 'NGN' }),
    });
    var code = (await rcpRes.json()).data.recipient_code;
    await db.borrowers.update(borrower.id, { paystack_recipient_code: code });
    borrower.paystack_recipient_code = code;
  }

  // Disburse
  await fetch('https://api.paystack.co/transfer', {
    method: 'POST',
    headers: { Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ source: 'balance', amount: loan.principal, recipient: borrower.paystack_recipient_code, reason: 'Loan disbursement #' + loanId }),
  });
  await db.loans.update(loanId, { status: 'disbursed', disbursed_at: new Date() });

  // Generate repayment schedule
  var installment = calculateInstallment(loan.principal, loan.interest_rate, loan.term_weeks);
  for (var i = 1; i <= loan.term_weeks; i++) {
    var dueDate = new Date();
    dueDate.setDate(dueDate.getDate() + (i * 7));
    var reference = 'REPAY-' + loanId + '-' + i;
    await db.repayments.create({ loan_id: loanId, installment_number: i, due_date: dueDate, amount_due: installment, status: 'pending', paystack_ref: reference });
  }
  await sendDisbursementNotification(borrower.phone, loan.principal / 100, loan.term_weeks);
}

// Send payment link for each installment due
async function sendRepaymentLink(borrowerEmail, repaymentId) {
  var repayment = await db.repayments.findById(repaymentId);
  var res = await fetch('https://api.paystack.co/transaction/initialize', {
    method: 'POST',
    headers: { Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: borrowerEmail,
      amount: repayment.amount_due,
      currency: 'NGN',
      reference: repayment.paystack_ref,
      metadata: { repayment_id: repaymentId, loan_id: repayment.loan_id, installment: repayment.installment_number },
    }),
  });
  return (await res.json()).data.authorization_url;
}

// Webhook: record repayment
if (event.event === 'charge.success') {
  var meta = event.data.metadata;
  if (!meta.repayment_id) return res.sendStatus(200);

  await db.repayments.update(meta.repayment_id, {
    status: 'paid',
    amount_paid: event.data.amount,
    paid_at: new Date(),
  });

  // Check if loan is fully repaid
  var pendingCount = await db.repayments.countPending(meta.loan_id);
  if (pendingCount === 0) {
    await db.loans.update(meta.loan_id, { status: 'completed' });
    await notifyBorrowerLoanComplete(meta.loan_id);
  }
}

// Cron: flag overdue repayments and apply late penalty
async function processOverdueRepayments() {
  var graceDeadline = new Date();
  graceDeadline.setDate(graceDeadline.getDate() - 3); // 3-day grace

  var overdue = await db.repayments.findAll({ status: 'pending', due_date_lt: graceDeadline });
  var LATE_PENALTY_RATE = 0.02; // 2% of installment per week overdue

  for (var repayment of overdue) {
    var weeksOverdue = Math.floor((new Date() - new Date(repayment.due_date)) / (7 * 24 * 60 * 60 * 1000));
    var penalty = Math.floor(repayment.amount_due * LATE_PENALTY_RATE * weeksOverdue);
    await db.repayments.update(repayment.id, { status: 'overdue', late_penalty: penalty });
    await notifyBorrowerOverdue(repayment.loan_id, repayment.installment_number, penalty / 100);
  }
}

See build a savings goal app with scheduled debits for card tokenization auto-debit — the same pattern used for recurring loan repayments.

Sign up for the McTaba newsletter