Till Add Cash Transaction

Add cash to a teller till (increase till balance).

Overview

A Till Add Cash transaction increases the cash balance of a teller till. This operation is typically used when:

• Opening a till for the day (initial cash float)
• Replenishing till during the day (additional cash)
• Transferring cash from vault to till
• Recording cash received from other sources

Key Characteristics:

• Purpose: Increase till cash balance
• Transaction Type: Till management operation
• Source: Branch vault, head teller, or other authorized source
• Impact: Till balance increased, source account decreased
• Audit: Full audit trail with impact tracking
• Authorization: Requires till owner or authorized user

---

Transaction Flow

---

Entities Impacted

Scenario: Add ₦100,000 Cash to Till from Branch Vault

Context:

• Till: TILL-001 (Teller: Jane Doe)
• Current Till Balance: ₦250,000
• Maximum Till Balance: ₦1,000,000
• Amount to Add: ₦100,000
• Source: Branch Vault

TransactionImpactRecord

{
  transactionId: "TXN-TILL-ADD-20251229-0001",
  transactionType: "ADD_CASH_TO_TILL",
  transactionState: "SETTLED",
  transactionDate: "2025-12-29T09:00:00Z",
  amount: 100000.00,
  impactedEntities: [
    // Teller Till
    {
      entityType: "TellerTill",
      entityId: 101,
      entityKey: "TILL-001",
      fieldName: "CashBalance",
      oldValue: 250000.00,
      newValue: 350000.00,
      deltaAmount: +100000.00,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 101,
      entityKey: "TILL-001",
      fieldName: "AvailableBalance",
      oldValue: 250000.00,
      newValue: 350000.00,
      deltaAmount: +100000.00,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 101,
      entityKey: "TILL-001",
      fieldName: "TotalCashIn",
      oldValue: 500000.00,
      newValue: 600000.00,
      deltaAmount: +100000.00,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 101,
      entityKey: "TILL-001",
      fieldName: "TransactionCount",
      oldValue: 25,
      newValue: 26,
      deltaAmount: +1,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 101,
      entityKey: "TILL-001",
      fieldName: "LastUpdateDate",
      oldValue: "2025-12-29T08:30:00Z",
      newValue: "2025-12-29T09:00:00Z",
      deltaAmount: 0,
      isReversal: false
    },
    // Branch Vault (if source is vault)
    {
      entityType: "BranchVault",
      entityId: 5,
      entityKey: "VAULT-HQ-001",
      fieldName: "CashBalance",
      oldValue: 5000000.00,
      newValue: 4900000.00,
      deltaAmount: -100000.00,
      isReversal: false
    },
    // GL Accounts
    {
      entityType: "GLAccount",
      entityKey: "1100-001",  // Cash-in-Till
      fieldName: "DebitAmount",
      deltaAmount: +100000.00
    },
    {
      entityType: "GLAccount",
      entityKey: "1100-002",  // Branch Vault
      fieldName: "CreditAmount",
      deltaAmount: +100000.00
    }
  ]
}

---

V2 API Commands

BankLingo V2 provides a BPMCore-compatible command for till cash management.

Architecture Overview

The V2 till add cash command follows the BPMCore Command Pattern:

• V2 Command: AddCashToTellerTillCommand (BPMCore compatible)
• BPM Integration: Accepts parameters via BpmUtil.GetPropertyValue()
• Impact Tracking: Full impact tracking via TransactionImpactTracker
• State Management: PENDING → APPROVED → SETTLED
• Approval Workflow: Configurable approval thresholds

Implementation: CB.Administration.Api/Commands/BPMCore/Tellering/AdministrationCoreTelleringTransactionCommandHandlers.cs

---

AddCashToTellerTillCommand

Purpose: Add cash to a teller till (increase till balance)

Command: AddCashToTellerTillCommand

Transaction State: PENDING → SETTLED

BPM Parameters

{
  "commandName": "AddCashToTellerTillCommand",
  "data": {
    "tillId": "string (mandatory)",
    "amount": "decimal (mandatory)",
    "sourceAccountKey": "string (optional)",
    "sourceType": "string (optional)",
    "transactionDate": "DateTime (optional)",
    "notes": "string (optional)"
  }
}

Parameter Details

Parameter	Type	Required	Description
tillId	string	✅ Yes	Teller till ID receiving cash
amount	decimal	✅ Yes	Cash amount to add (must be > 0)
sourceAccountKey	string	❌ No	Source account (vault/GL account)
sourceType	string	❌ No	Source type (e.g., "VAULT", "GL")
transactionDate	DateTime	❌ No	Transaction date (defaults to today)
notes	string	❌ No	Transaction notes/remarks

Balance Impact

Teller Till:

Balance Field	Change	Reason
CashBalance	+amount	Cash added
AvailableBalance	+amount	Available for transactions
TotalCashIn	+amount	Track total inflow
TransactionCount	+1	Transaction counter
LastUpdateDate	Set to now	Track last update

Source Account (if specified):

Balance Field	Change	Reason
CashBalance	-amount	Cash transferred out
AvailableBalance	-amount	Funds moved

Validation Rules

✅ Till Validation:

• Till must exist
• Till state must be OPENED
• User must be authorized for till operations
• Current balance + amount ≤ Maximum till balance

✅ Amount Validation:

• Amount must be > 0
• Amount must not exceed till maximum capacity
• Amount currency must match till currency

✅ Source Validation (if source specified):

• Source account must exist and be active
• Source account must have sufficient balance
• Source account currency must match till currency

❌ Rejection Scenarios:

• Till not found or not opened
• Amount exceeds till maximum balance
• Source account insufficient funds
• User not authorized for till
• Till locked or suspended

Transaction States

States:

1. PENDING: Transaction initiated, awaiting approval (if required)
2. APPROVED: Approved, ready for execution
3. SETTLED: Cash added, till balance increased
4. REJECTED: Transaction rejected (no balance change)

Approval Workflow

• ✅ Auto-approval if amount < configured limit (e.g., ₦50,000)
• ⚠️ Manual approval required if amount ≥ limit
• 🔒 Transaction pending during approval
• 🔓 No balance hold (till not yet credited)

Example Request/Response

Request:

{
  "commandName": "AddCashToTellerTillCommand",
  "data": {
    "tillId": "TILL-001",
    "amount": 100000.00,
    "sourceAccountKey": "VAULT-HQ-001",
    "sourceType": "VAULT",
    "transactionDate": "2025-12-29T09:00:00Z",
    "notes": "Morning till replenishment from branch vault"
  }
}

Response:

{
  "isSuccessful": true,
  "transactionId": "TXN-TILL-ADD-20251229-0001",
  "transactionState": "SETTLED",
  "message": "Cash added to till successfully",
  "data": {
    "tillId": "TILL-001",
    "tillOwner": "Jane Doe",
    "amount": 100000.00,
    "transactionDate": "2025-12-29T09:00:00Z",
    "tillBalance": {
      "previousBalance": 250000.00,
      "newBalance": 350000.00,
      "maximumBalance": 1000000.00,
      "utilizationPercent": 35.0
    },
    "sourceAccount": {
      "accountKey": "VAULT-HQ-001",
      "accountType": "VAULT",
      "previousBalance": 5000000.00,
      "newBalance": 4900000.00
    },
    "impactRecords": 8
  }
}

Impact Tracking

Impacted Entities:

• ✅ Teller Till (5 field changes: cash balance, available balance, total cash in, transaction count, last update)
• ✅ Source Account (2 field changes: cash balance, available balance) - if specified
• ✅ GL Accounts (journal entries for cash movement)

Use Cases

1. Morning Till Opening:

{
  "tillId": "TILL-001",
  "amount": 200000.00,
  "sourceAccountKey": "VAULT-HQ-001",
  "notes": "Morning float - till opening"
}

2. Mid-Day Replenishment:

{
  "tillId": "TILL-003",
  "amount": 150000.00,
  "sourceAccountKey": "VAULT-HQ-001",
  "notes": "Replenishment - low cash alert"
}

3. Cash Transfer from Another Till:

{
  "tillId": "TILL-002",
  "amount": 50000.00,
  "sourceAccountKey": "TILL-001",
  "sourceType": "TILL",
  "notes": "Transfer from TILL-001 (excess cash)"
}

Error Handling

Common Errors:

Error	Reason	Resolution
TILL_NOT_OPENED	Till is not in OPENED state	Open till first
EXCEEDS_TILL_MAXIMUM	Amount exceeds till capacity	Reduce amount or increase limit
SOURCE_INSUFFICIENT_FUNDS	Source account has insufficient balance	Fund source account first
UNAUTHORIZED_USER	User not authorized for till	Use authorized user or till owner
TILL_LOCKED	Till is locked or suspended	Unlock till first

Business Rules

1. Till Maximum Balance: Each till has a maximum cash capacity (e.g., ₦1,000,000)
2. Daily Limits: May have daily add cash limits for security
3. Authorization: Only till owner or authorized users can add cash
4. Audit Trail: All cash additions fully audited with user, timestamp, source
5. Concurrent Safety: Uses locking to prevent concurrent till modifications
6. Reversal: Transactions can be reversed if posted in error (see ReverseTransactionCommand)

Related Operations

• Remove Cash: RemoveCashFromTellerTillCommand (decrease till balance)
• Till Transfer: TransferBetweenTellerTillCommand (move cash between tills)
• Vault Funding: FundBranchVaultAccountCommand (add cash to vault)
• Till Closure: CloseTellerTillCommand (close till and transfer balance)

---

Performance Considerations

• Till Locking: Uses row-level locking on till record during transaction
• Transaction Time: Typically < 50ms for simple add cash operation
• Impact Records: Creates 5-10 impact entries per transaction
• Concurrent Operations: Serialized per till to prevent race conditions
• Validation: All validations complete before balance changes

---

Audit and Compliance

Audit Trail

Every add cash transaction records:

• ✅ User who initiated transaction
• ✅ Timestamp of transaction
• ✅ Amount added
• ✅ Source of cash (vault/GL/other till)
• ✅ Till owner and ID
• ✅ Approval details (if applicable)
• ✅ Before/after balances

Compliance Reports

Daily Till Activity Report:

• All cash additions per till
• Total cash added per teller
• Source breakdown (vault vs other)
• Exception transactions (large amounts)

Till Balance Monitoring:

• Real-time till balance tracking
• Maximum balance breach alerts
• Unusual activity detection

---

Related Documentation

• Till Remove Cash - Remove cash from till
• Till to Till Transfer - Transfer between tills
• Vault Funding - Add cash to branch vault
• Teller Deposit - Customer deposit via till
• Teller Transactions Overview - Main transaction index

---

Developer Resources

For API implementation details, see:

• Add Cash to Till API - Developer Guide
• Till Accounts API Reference

---

Navigation:

• ← Back to Vault Funding
• → Next: Till Remove Cash
• ↑ Back to Transaction Processing