Loan Repayment via Teller

Customer repays loan installment via teller counter (Cash payment).

Overview

Loan repayment via teller allows customers to pay their loan obligations through cash presented at the teller counter. The transaction reduces the loan balances (Principal, Interest, Penalties, Fees) and increases the teller till balance.

Key Features:

Cash payment through teller
Payment allocation (Interest â†’ Principal â†’ Penalties â†’ Fees)
Loan schedule tracking and updates
Till balance impact
Multiple schedule support (for restructured loans)
Approval workflow for early settlements
Concurrent transaction safety with impact tracking

Transaction Flow

Entities Impacted

Standard Repayment Scenario

Command: LoanRepaymentWithTellerCommand (BPMCore)

Payment: â‚¦15,000 allocated as:

Interest: â‚¦5,000
Principal: â‚¦10,000

ImpactedEntities:
[
  {
    entityType: "LoanAccount",
    entityId: 54321,
    fieldName: "InterestBalance",
    oldValue: 50000.00,
    newValue: 45000.00,
    deltaAmount: -5000.00
  },
  {
    entityType: "LoanAccount",
    entityId: 54321,
    fieldName: "PrincipalBalance",
    oldValue: 500000.00,
    newValue: 490000.00,
    deltaAmount: -10000.00
  },
  {
    entityType: "LoanSchedule",
    entityId: 1001,
    fieldName: "InterestPaid",
    oldValue: 0.00,
    newValue: 5000.00,
    deltaAmount: +5000.00
  },
  {
    entityType: "LoanSchedule",
    entityId: 1001,
    fieldName: "PrincipalPaid",
    oldValue: 0.00,
    newValue: 10000.00,
    deltaAmount: +10000.00
  },
  {
    entityType: "LoanSchedule",
    entityId: 1001,
    fieldName: "State",
    oldValue: "ACTIVE",
    newValue: "PAID",
    deltaAmount: 0
  },
  {
    entityType: "TellerTill",
    entityId: 789,
    fieldName: "CashBalance",
    oldValue: 50000.00,
    newValue: 65000.00,
    deltaAmount: +15000.00
  },
  {
    entityType: "TellerTill",
    entityId: 789,
    fieldName: "TransactionCount",
    oldValue: 42,
    newValue: 43,
    deltaAmount: +1
  },
  {
    entityType: "GLAccount",
    entityKey: "1050-CASH-IN-TILL",
    fieldName: "DebitAmount",
    deltaAmount: +15000.00
  },
  {
    entityType: "GLAccount",
    entityKey: "3001-LOANS-RECEIVABLE",
    fieldName: "CreditAmount",
    deltaAmount: +10000.00
  },
  {
    entityType: "GLAccount",
    entityKey: "4001-INTEREST-INCOME",
    fieldName: "CreditAmount",
    deltaAmount: +5000.00
  }
]
```text
### Repayment with Penalties & Fees

**Payment**: â‚¦20,000 allocated as:
- Interest: â‚¦5,000
- Principal: â‚¦10,000
- Penalty: â‚¦3,000
- Fees: â‚¦2,000

```typescript
ImpactedEntities:
[
  // LoanAccount balances...
  {
    entityType: "LoanAccount",
    entityId: 54321,
    fieldName: "PenaltyBalance",
    oldValue: 5000.00,
    newValue: 2000.00,
    deltaAmount: -3000.00
  },
  {
    entityType: "LoanAccount",
    entityId: 54321,
    fieldName: "FeeBalance",
    oldValue: 10000.00,
    newValue: 8000.00,
    deltaAmount: -2000.00
  },
  // LoanSchedule updates...
  {
    entityType: "LoanSchedule",
    entityId: 1001,
    fieldName: "PenaltyBalance",
    oldValue: 3000.00,
    newValue: 0.00,
    deltaAmount: -3000.00
  },
  {
    entityType: "LoanSchedule",
    entityId: 1001,
    fieldName: "FeeBalance",
    oldValue: 2000.00,
    newValue: 0.00,
    deltaAmount: -2000.00
  },
  // Additional GL entries...
  {
    entityType: "GLAccount",
    entityKey: "4002-PENALTY-INCOME",
    fieldName: "CreditAmount",
    deltaAmount: +3000.00
  },
  {
    entityType: "GLAccount",
    entityKey: "4003-FEE-INCOME",
    fieldName: "CreditAmount",
    deltaAmount: +2000.00
  }
]
```text
---

## Implementation

### Loan Repayment with Teller Implementation

**BPMCore Command**: `LoanRepaymentWithTellerCommand`

:::warning[Code Removed]
**Implementation details removed for security.**

Contact support for implementation guidance.
:::text
---

## Payment Allocation Rules

### Allocation Order

Payments are allocated in the following priority:

1. **Interest** (oldest schedule first)
2. **Principal** (oldest schedule first)
3. **Penalties** (account-level)
4. **Fees** (account-level)

### Example Allocation

**Loan State**:
- Schedule 1 (Due Jan 15): Interest â‚¦5,000, Principal â‚¦10,000
- Schedule 2 (Due Feb 15): Interest â‚¦5,000, Principal â‚¦10,000
- Penalty Balance: â‚¦3,000
- Fee Balance: â‚¦2,000

**Payment**: â‚¦18,000

**Allocation**:

```text
1. Interest (Schedule 1): â‚¦5,000  â†’ Remaining: â‚¦13,000
2. Interest (Schedule 2): â‚¦5,000  â†’ Remaining: â‚¦8,000
3. Principal (Schedule 1): â‚¦8,000  â†’ Remaining: â‚¦0

Result:
- Schedule 1: Interest PAID (â‚¦5,000), Principal PARTIAL (â‚¦8,000/â‚¦10,000)
- Schedule 2: Interest PAID (â‚¦5,000), Principal NOT PAID
- Penalties: â‚¦3,000 (unpaid)
- Fees: â‚¦2,000 (unpaid)
```text
---

## Validation Rules

### Till Validation

| Rule | Check | Error Message |
|------|-------|---------------|
| **Till Exists** | Till found by `TillId` or `EncodedKey` | "Till not found" |
| **Till State** | `TillAccountState == OPENED` | "Till {TillId} is not opened" |
| **Till Type** | `TillType == TellerTill` | "Invalid till type" |
| **Currency Match** | Till currency == Loan currency | "Currency mismatch" |
| **Maximum Balance** | `Balance + Amount <= MaximumBalance` (if Hard constraint) | "Transaction will exceed till maximum balance by {excess}" |

### Loan Validation

| Rule | Check | Error Message |
|------|-------|---------------|
| **Loan Exists** | Loan found by `AccountNumber` and `ClientEncodedKey` | "Loan account not found" |
| **Loan Active** | `LoanState == ACTIVE` | "Loan account is not active" |
| **Not Closed** | `LoanState != CLOSED` | "Loan account is closed" |
| **Not Written Off** | `LoanState != WRITTEN_OFF` | "Loan account has been written off" |
| **Active Schedules** | At least one active schedule exists | "No active loan schedules found" |
| **Amount Valid** | `Amount > 0` | "Payment amount must be greater than zero" |

---

## GL Account Postings

### Standard Repayment

| Account | Debit (Dr) | Credit (Cr) | Description |
|---------|------------|-------------|-------------|
| **Cash-in-Till Asset** | Amount | - | Increase till cash |
| **Loans Receivable Asset** | - | Principal | Reduce loan asset |
| **Interest Income** | - | Interest | Recognize interest revenue |
| **Penalty Income** | - | Penalty | Recognize penalty revenue |
| **Fee Income** | - | Fees | Recognize fee revenue |

**Example** (â‚¦20,000 payment: â‚¦5K interest, â‚¦10K principal, â‚¦3K penalty, â‚¦2K fees):

```text
DR: 1050-Cash-in-Till                 â‚¦20,000
CR: 3001-Loans-Receivable             â‚¦10,000
CR: 4001-Interest-Income               â‚¦5,000
CR: 4002-Penalty-Income                â‚¦3,000
CR: 4003-Fee-Income                    â‚¦2,000
```text
---

## Testing

### Test Scenario 1: Standard Installment Payment

**Setup**:
- Loan: â‚¦500,000 principal, â‚¦50,000 interest balance
- Schedule Due: Interest â‚¦5,000, Principal â‚¦10,000
- Payment: â‚¦15,000 (exact installment)

**Expected Results**:

```typescript
LoanAccount:
  InterestBalance: 50000 â†’ 45000 âœ“
  PrincipalBalance: 500000 â†’ 490000 âœ“

LoanSchedule:
  InterestPaid: 0 â†’ 5000 âœ“
  PrincipalPaid: 0 â†’ 10000 âœ“
  State: ACTIVE â†’ PAID âœ“

TellerTill:
  Balance: +15000 âœ“
  TransactionCount: +1 âœ“

GLEntries:
  DR: Cash-in-Till: â‚¦15,000 âœ“
  CR: Loans-Receivable: â‚¦10,000 âœ“
  CR: Interest-Income: â‚¦5,000 âœ“
```text
### Test Scenario 2: Partial Payment

**Setup**:
- Schedule Due: Interest â‚¦5,000, Principal â‚¦10,000
- Payment: â‚¦8,000 (partial)

**Expected Results**:

```typescript
Allocation:
  Interest: â‚¦5,000 (full) âœ“
  Principal: â‚¦3,000 (partial) âœ“

LoanSchedule:
  InterestPaid: 0 â†’ 5000 âœ“
  PrincipalPaid: 0 â†’ 3000 âœ“
  State: ACTIVE (not fully paid) âœ“
```text
### Test Scenario 3: Multiple Schedules

**Setup**:
- Schedule 1: Interest â‚¦5K, Principal â‚¦10K
- Schedule 2: Interest â‚¦5K, Principal â‚¦10K
- Payment: â‚¦25,000

**Expected Results**:

```typescript
Allocation:
  Schedule 1 Interest: â‚¦5,000 âœ“
  Schedule 2 Interest: â‚¦5,000 âœ“
  Schedule 1 Principal: â‚¦10,000 âœ“
  Schedule 2 Principal: â‚¦5,000 (partial) âœ“

Schedule 1: PAID âœ“
Schedule 2: ACTIVE (partial payment) âœ“
```text
### Test Scenario 4: Full Settlement with Penalties

**Setup**:
- Remaining Principal: â‚¦50,000
- Remaining Interest: â‚¦5,000
- Penalty Balance: â‚¦3,000
- Payment: â‚¦58,000 (full settlement)

**Expected Results**:

```typescript
LoanAccount:
  PrincipalBalance: 50000 â†’ 0 âœ“
  InterestBalance: 5000 â†’ 0 âœ“
  PenaltyBalance: 3000 â†’ 0 âœ“
  LoanState: ACTIVE â†’ CLOSED âœ“
  ClosedDate: Set âœ“

GLEntries:
  DR: Cash-in-Till: â‚¦58,000 âœ“
  CR: Loans-Receivable: â‚¦50,000 âœ“
  CR: Interest-Income: â‚¦5,000 âœ“
  CR: Penalty-Income: â‚¦3,000 âœ“

V2 API Commands

Architecture Overview

The V2 loan repayment with deposit command follows the Delegation Pattern:

V2 Facade: InitiateLoanRepaymentWithDepositCommand (BPMCore compatible)
V1 Implementation: Delegates to existing V1 LoanRepaymentWithDepositCommand with full business logic
BPM Integration: Accepts parameters via BpmUtil.GetPropertyValue()

Implementation: CB.Administration.Api/Commands/BPMCore/Loans/AdministrationCoreLoanCommandHandlers.Transactions.cs

InitiateLoanRepaymentWithDepositCommand

Purpose: Process loan repayment via cash deposit to teller till (no deposit account needed)

Command: InitiateLoanRepaymentWithDepositCommand

Delegation: â†’ LoanRepaymentWithDepositCommand (V1 implementation)

BPM Parameters

{
  "commandName": "InitiateLoanRepaymentWithDepositCommand",
  "data": {
    "accountEncodedKey": "string (mandatory)",
    "clientEncodedKey": "string (mandatory)",
    "paymentAmount": "decimal (mandatory)",
    "tillId": "string (mandatory)",
    "transactionDate": "DateTime (optional)",
    "notes": "string (optional)"
  }
}

Parameter Details

Parameter	Type	Required	Description
`accountEncodedKey`	string	âœ… Yes	Loan account for repayment
`clientEncodedKey`	string	âœ… Yes	Client/borrower encoded key
`paymentAmount`	decimal	âœ… Yes	Cash payment amount (must be > 0)
`tillId`	string	âœ… Yes	Teller till ID receiving cash
`transactionDate`	DateTime	âŒ No	Payment date (defaults to today)
`notes`	string	âŒ No	Repayment notes/remarks

Balance Impact

Loan Account: (same as regular repayment)

âœ… PrincipalBalance, InterestBalance, PenaltyBalance, FeesBalance reduced
âœ… Payment allocated across schedules (Penalty â†’ Interest â†’ Fees â†’ Principal)

Teller Till:

Balance Field	Change	Reason
`TillBalance`	+paymentAmount	Cash received
`TotalCashIn`	+paymentAmount	Track cash inflow

No Deposit Account Impact: Customer pays cash directly (no deposit account debit)

Example Response

{
  "isSuccessful": true,
  "transactionId": "TXN-LOAN-RPMT-TELLER-20251229-0001",
  "transactionState": "SETTLED",
  "message": "Loan repayment with cash deposit processed successfully",
  "data": {
    "loanAccountKey": "8a8080827f23loan017f23def456",
    "paymentAmount": 50000.00,
    "tillId": "TILL-001",
    "allocation": {
      "penaltyPaid": 2000.00,
      "interestPaid": 15000.00,
      "feesPaid": 1000.00,
      "principalPaid": 32000.00
    },
    "tillBalance": {
      "previousBalance": 500000.00,
      "newBalance": 550000.00
    },
    "schedulesAffected": 2
  }
}

Loan Repayment - General loan repayment processing
Loan Disbursement - Loan disbursement process
Teller Deposit - Teller deposit transactions
Transaction Impact Tracking - Delta-based tracking system

Developer Resources

For API implementation details, see:

Overview​

Transaction Flow​

Entities Impacted​

Standard Repayment Scenario​

V2 API Commands​

Architecture Overview​

InitiateLoanRepaymentWithDepositCommand​

BPM Parameters​

Parameter Details​

Balance Impact​

Example Response​

Related Documentation​

Developer Resources​