Teller & Till Transactions Overview

Complete guide to teller operations and till management in BankLingo V2 Core Banking Platform.

Overview

Teller transactions handle all cash-based operations through bank tellers, including deposits, withdrawals, till management, and vault operations. BankLingo V2 implements a robust teller transaction processing engine with:

Till impact tracking: Every till balance change tracked
Cash movement audit: Complete trail of physical cash handling
Multi-phase processing: PENDING → APPROVED → COMPLETED → ACTIVE
Balance validation: Till min/max enforcement
Complete audit trail: Every cash movement recorded
Universal reversal: One framework works for all transaction types

Transaction Categories

Teller Customer Transactions

Transaction	Purpose	V2 Command	Key Features
Teller Deposit	Deposit via teller (Cash/Cheque)	`InitiateDepositCommand` (with tillId)	Till impact, cash tracking, cheque clearing, account activation
Teller Withdrawal	Withdraw via teller (Cash/Cheque)	`InitiateWithdrawalCommand` (with tillId)	Till disbursement, hold management, cash verification, limit checks
Loan Repayment (Teller)	Loan payment via teller	`InitiateLoanRepaymentWithDepositCommand`	Payment allocation, schedule updates, till impact, GL income

Till Operations

Transaction	Purpose	V2 Command	Key Features
Add Cash to Till	Add cash to teller till	`AddCashToTellerTillCommand`	Maximum balance enforcement, source tracking, audit trail
Remove Cash from Till	Remove cash from teller till	`RemoveCashFromTellerTillCommand`	Minimum balance enforcement, physical transfer, approval workflow
Till to Till Transfer	Transfer cash between tills	`TransferBetweenTellerTillCommand`	Atomic dual-till operation, balance validation, handover process

Transaction States

All teller transactions follow a state machine:

States Explained:

PENDING: Created, physical cash verification in progress
APPROVED: Verified, ready to execute
REJECTED: Denied before execution
COMPLETED: Executed, till balances and accounts updated
ACTIVE: Finalized, permanent
REVERSED: Undone via compensating transaction
CANCELLED: Cancelled before completion
FAILED: Execution failed

Core Concepts

Till Management

Each teller has an assigned till (cash drawer) with:

Opening Balance: Starting cash at day/shift start
Current Balance: Real-time cash balance
Minimum Balance: Required reserve (cannot go below)
Maximum Balance: Security limit (must transfer excess)
Currency: Assigned currency (single-currency tills)
Status: OPEN, CLOSED, SUSPENDED

Till Balance Formula:

Current Balance = Opening Balance + Deposits - Withdrawals + Additions - Removals

Cash Movement Tracking

Every cash transaction creates an audit record:

TillTransaction {
  tillId: "TILL-001"
  transactionType: "DEPOSIT" | "WITHDRAWAL" | "ADD" | "REMOVE" | "TRANSFER"
  amount: 5000
  oldBalance: 50000
  newBalance: 55000
  physicalVerification: true
  verifiedBy: "TELLER-123"
  timestamp: "2026-01-04T10:30:00"
}

Why this matters:

Complete audit trail for cash handling
Enables accurate till reconciliation
Supports reversal and corrections
Detects discrepancies immediately

Impact Tracking

Every teller transaction records exactly what changed:

ImpactedEntity {
  entityType: "TellerTill"
  entityId: 123
  fieldName: "CurrentBalance"
  oldValue: 50000
  newValue: 55000
  deltaAmount: +5000  // The actual cash movement
}

GL Integration

All teller transactions automatically post to General Ledger:

Teller Deposit Example:

DR: Till Cash Account              +5,000
CR: Customer Deposits              -5,000

Teller Withdrawal Example:

DR: Customer Deposits              +5,000
CR: Till Cash Account              -5,000

Till Addition Example:

DR: Till Cash Account              +10,000
CR: Vault Cash Account             -10,000

Till Balance Limits

Maximum Balance Enforcement

When till balance exceeds maximum:

Alert: System notifies teller
Action Required: Transfer excess to vault
Restriction: No further deposits until resolved
Compliance: Regulatory and security requirement

Minimum Balance Enforcement

When till balance falls below minimum:

Alert: System notifies teller
Action Required: Request replenishment from vault
Restriction: Large withdrawals blocked
Operations: Ensures sufficient cash for operations

Approval Workflows

Teller transactions can require approval based on:

Transaction amount (threshold)
Till balance impact
Removal requests (security)
Transfer between tills (audit)
User permissions

Workflow:

Initiate Teller Transaction (PENDING)
    ↓
Physical Cash Verification
    ↓
Check Approval Requirement
    ↓
Auto-Approve OR Await Approval
    ↓
Execute Transaction (COMPLETED)
    ↓
Update Till Balance & Account

API Integration

All teller transactions are executed via BPMCore command pattern:

Endpoint:

POST /api/bpm/cmd
Content-Type: application/json
Authorization: Bearer {access_token}

Request Structure - Teller Deposit:

{
  "commandName": "InitiateDepositCommand",
  "data": {
    "accountEncodedKey": "ACC-001",
    "amount": 5000.00,
    "tillId": "TILL-001",
    "channelCode": "TELLER",
    "notes": "Cash deposit via teller"
  }
}

Request Structure - Till Addition:

{
  "commandName": "AddCashToTellerTillCommand",
  "data": {
    "tillId": "TILL-001",
    "amount": 10000.00,
    "source": "VAULT",
    "notes": "Morning replenishment"
  }
}

Response:

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Transaction completed successfully",
  "data": {
    "transactionKey": "TXN-2025-001",
    "tillId": "TILL-001",
    "tillBalance": {
      "previous": 50000.00,
      "current": 60000.00
    },
    "transactionState": "COMPLETED"
  }
}

End-of-Day (EOD) Reconciliation

Till Closing Process

Count Physical Cash: Teller counts all cash in till
Compare with System: System balance vs. physical count
Record Variance: Any discrepancy recorded
Transfer Excess: Move cash to vault
Close Till: Lock till for the day

Variance Handling

Cash Short (Physical < System):

System Balance: 50,000
Physical Count: 49,500
Variance: -500 (short)

GL Entry:
DR: Cash Short/Over (Expense)    +500
CR: Till Cash Account             -500

Cash Over (Physical > System):

System Balance: 50,000
Physical Count: 50,200
Variance: +200 (over)

GL Entry:
DR: Till Cash Account             +200
CR: Cash Short/Over (Income)      -200

Concurrent Transaction Safety

BankLingo V2 ensures till integrity in concurrent scenarios:

Optimistic Locking

Every till has a Version field that increments with each update. Concurrent updates detected and retried.

Delta-Based Tracking

Changes tracked as deltas, not snapshots, preserving concurrent modifications.

Example Scenario

Time 10:00 - Till Balance: 50,000
Time 10:01 - Deposit 5,000 PENDING
Time 10:02 - Withdrawal 2,000 COMPLETED (balance: 48,000)
Time 10:03 - Deposit 5,000 COMPLETED (balance: 53,000)

Final: 53,000 ✓ (both transactions preserved)

Error Handling

All transactions use standard error codes:

Error Code	Description	Action
`00`	Success	Transaction completed
`01`	Insufficient till cash	Request replenishment
`05`	Till closed/suspended	Cannot transact
`12`	Invalid amount	Verify amount
`51`	Limit exceeded	Transfer to vault
`91`	System error	Retry or contact support

Best Practices

For Tellers

Count cash carefully before and after transactions
Verify customer identity for withdrawals
Keep till organized (sort by denomination)
Report discrepancies immediately
Never leave till unattended
Follow physical security protocols

For Supervisors

Monitor till balances throughout day
Approve large transactions promptly
Verify EOD reconciliations
Investigate variances immediately
Ensure adequate vault cash
Review audit trails regularly

For Developers

Always track till impact in transactions
Use delta-based tracking for balances
Implement proper locking mechanisms
Test concurrent transaction scenarios
Validate till limits before execution
Log all cash movements

Next Steps

Explore specific transaction types:

For implementation:

Last Updated: January 4, 2026
Version: 2.0
Status: Production Ready

Overview​

Transaction Categories​

Teller Customer Transactions​

Till Operations​

Transaction States​

Core Concepts​

Till Management​

Cash Movement Tracking​

Impact Tracking​

GL Integration​

Till Balance Limits​

Maximum Balance Enforcement​

Minimum Balance Enforcement​

Approval Workflows​

API Integration​

End-of-Day (EOD) Reconciliation​

Till Closing Process​

Variance Handling​

Concurrent Transaction Safety​

Optimistic Locking​

Delta-Based Tracking​

Example Scenario​

Error Handling​

Best Practices​

For Tellers​

For Supervisors​

For Developers​

Next Steps​