Loan Repayment With Teller

Overview

Processes a loan repayment transaction through the teller till.

Command

LoanRepaymentWithTellerCommand

Endpoint

POST /api/bpm/cmd

Request Headers

Authorization: Bearer {access_token}
Content-Type: application/json
X-Tenant-Id: {tenant_id}

Request Body

{
  "cmd": "LoanRepaymentWithTellerCommand",
  "data": {
    "tillId": "TILL-T001",
    "loanAccountNumber": "LN-2024-001234",
    "amount": 50000.00,
    "paymentType": "PrincipalAndInterest",
    "narration": "Monthly loan repayment",
    "receiptNumber": "RCP-2024-789456"
  }
}

Request Parameters

Parameter	Type	Required	Description
cmd	string	Yes	Must be "LoanRepaymentWithTellerCommand"
data	object	Yes	Loan repayment data
↳ tillId	string	Yes	Unique identifier of the till
↳ loanAccountNumber	string	Yes	Loan account number
↳ amount	decimal	Yes	Repayment amount (must be positive)
↳ paymentType	string	Yes	Type of repayment (PrincipalAndInterest, PrincipalOnly, InterestOnly, Penalty, Fees)
↳ narration	string	Yes	Transaction description
↳ receiptNumber	string	No	Customer receipt reference number

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Loan repayment processed successfully",
  "data": {
    "transactionId": "string",
    "loanAccountNumber": "string",
    "amount": "decimal",
    "principalPaid": "decimal",
    "interestPaid": "decimal",
    "penaltyPaid": "decimal",
    "remainingBalance": "decimal",
    "transactionDate": "datetime",
    "transactionReference": "string"
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "message": "Validation failed",
  "errors": ["Loan account number is required", "Amount must be positive"]
}

404 Not Found

{
  "success": false,
  "message": "Loan account not found"
}

409 Conflict

{
  "success": false,
  "message": "Loan account is not active"
}

Business Rules

1. Till must be in "Open" status
2. Loan account must be active
3. Amount must be positive
4. Payment allocated based on payment type and loan terms
5. Creates audit trail entry
6. Updates both till and loan balance
7. Overpayments may be allowed based on configuration

Code Example

async function loanRepaymentWithTeller(tillId, loanAccountNumber, amount, narration) {
  const response = await fetch('/api/bpm/cmd', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      'X-Tenant-Id': tenantId
    },
    body: JSON.stringify({
      commandType: 'LoanRepaymentWithTellerCommand',
      data: {
        tillId: tillId,
        loanAccountNumber: loanAccountNumber,
        amount: amount,
        paymentType: 'PrincipalAndInterest',
        narration: narration
      }
    })
  });
  
  return await response.json();
}

Related Commands

• Deposit To Teller Till - Process deposit
• Retrieve Loan By ID - View loan details

Notes

• Verify loan account details before processing
• Issue receipt to customer after successful repayment
• Payment allocation follows bank's loan repayment policy
• Consider loan prepayment penalties if applicable
• Update till balance increases with repayment