Till Remove Cash Transaction

Remove cash from a teller till (decrease till balance).

Overview

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

Transferring excess cash to branch vault
Removing cash at end of day (till closure preparation)
Transferring cash to another till
Recording cash sent for deposit or secure transport

Key Characteristics:

Purpose: Decrease till cash balance
Transaction Type: Till management operation
Destination: Branch vault, another till, or GL account
Impact: Till balance decreased, destination account increased
Audit: Full audit trail with impact tracking
Authorization: Requires till owner or authorized user

Transaction Flow

Entities Impacted

Scenario: Remove ₦200,000 Cash from Till to Branch Vault

Context:

Till: TILL-002 (Teller: John Smith)
Current Till Balance: ₦550,000
Minimum Till Balance: ₦50,000
Amount to Remove: ₦200,000
Destination: Branch Vault

TransactionImpactRecord

{
  transactionId: "TXN-TILL-RMV-20251229-0001",
  transactionType: "REMOVE_CASH_FROM_TILL",
  transactionState: "SETTLED",
  transactionDate: "2025-12-29T16:30:00Z",
  amount: 200000.00,
  impactedEntities: [
    // Teller Till
    {
      entityType: "TellerTill",
      entityId: 102,
      entityKey: "TILL-002",
      fieldName: "CashBalance",
      oldValue: 550000.00,
      newValue: 350000.00,
      deltaAmount: -200000.00,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 102,
      entityKey: "TILL-002",
      fieldName: "AvailableBalance",
      oldValue: 550000.00,
      newValue: 350000.00,
      deltaAmount: -200000.00,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 102,
      entityKey: "TILL-002",
      fieldName: "TotalCashOut",
      oldValue: 300000.00,
      newValue: 500000.00,
      deltaAmount: +200000.00,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 102,
      entityKey: "TILL-002",
      fieldName: "TransactionCount",
      oldValue: 42,
      newValue: 43,
      deltaAmount: +1,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 102,
      entityKey: "TILL-002",
      fieldName: "LastUpdateDate",
      oldValue: "2025-12-29T15:45:00Z",
      newValue: "2025-12-29T16:30:00Z",
      deltaAmount: 0,
      isReversal: false
    },
    // Branch Vault (destination)
    {
      entityType: "BranchVault",
      entityId: 5,
      entityKey: "VAULT-HQ-001",
      fieldName: "CashBalance",
      oldValue: 4900000.00,
      newValue: 5100000.00,
      deltaAmount: +200000.00,
      isReversal: false
    },
    // GL Accounts
    {
      entityType: "GLAccount",
      entityKey: "1100-002",  // Branch Vault
      fieldName: "DebitAmount",
      deltaAmount: +200000.00
    },
    {
      entityType: "GLAccount",
      entityKey: "1100-001",  // Cash-in-Till
      fieldName: "CreditAmount",
      deltaAmount: +200000.00
    }
  ]
}

V2 API Commands

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

Architecture Overview

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

V2 Command: RemoveCashFromTellerTillCommand (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

RemoveCashFromTellerTillCommand

Purpose: Remove cash from a teller till (decrease till balance)

Command: RemoveCashFromTellerTillCommand

Transaction State: PENDING → SETTLED

BPM Parameters

{
  "commandName": "RemoveCashFromTellerTillCommand",
  "data": {
    "tillId": "string (mandatory)",
    "amount": "decimal (mandatory)",
    "destinationAccountKey": "string (optional)",
    "destinationType": "string (optional)",
    "removalReason": "string (optional)",
    "transactionDate": "DateTime (optional)",
    "notes": "string (optional)"
  }
}

Parameter Details

Parameter	Type	Required	Description
`tillId`	string	✅ Yes	Teller till ID to remove cash from
`amount`	decimal	✅ Yes	Cash amount to remove (must be > 0)
`destinationAccountKey`	string	❌ No	Destination account (vault/GL account)
`destinationType`	string	❌ No	Destination type (e.g., "VAULT", "GL", "TILL")
`removalReason`	string	❌ No	Reason code (e.g., "EXCESS_CASH", "END_OF_DAY")
`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 removed
`AvailableBalance`	-amount	Funds withdrawn
`TotalCashOut`	+amount	Track total outflow
`TransactionCount`	+1	Transaction counter
`LastUpdateDate`	Set to now	Track last update

Destination Account (if specified):

Balance Field	Change	Reason
`CashBalance`	+amount	Cash received
`AvailableBalance`	+amount	Funds added

Validation Rules

✅ Till Validation:

Till must exist
Till state must be OPENED
User must be authorized for till operations
Current balance >= amount (sufficient funds)
Current balance - amount >= Minimum till balance

✅ Amount Validation:

Amount must be > 0
Amount must not leave till below minimum balance
Amount currency must match till currency

✅ Destination Validation (if destination specified):

Destination account must exist and be active
Destination account currency must match till currency

❌ Rejection Scenarios:

Till not found or not opened
Insufficient till balance
Amount would leave till below minimum balance
User not authorized for till
Till locked or suspended

Transaction States

States:

PENDING: Transaction initiated, awaiting approval (if required)
APPROVED: Approved, ready for execution
SETTLED: Cash removed, till balance decreased
REJECTED: Transaction rejected (no balance change)

Approval Workflow

✅ Auto-approval if amount < configured limit (e.g., ₦100,000)
⚠️ Manual approval required if amount ≥ limit
🔒 Amount placed on hold during approval (available balance reduced)
🔓 Hold released on rejection

Example Request/Response

Request:

{
  "commandName": "RemoveCashFromTellerTillCommand",
  "data": {
    "tillId": "TILL-002",
    "amount": 200000.00,
    "destinationAccountKey": "VAULT-HQ-001",
    "destinationType": "VAULT",
    "removalReason": "EXCESS_CASH",
    "transactionDate": "2025-12-29T16:30:00Z",
    "notes": "End of day - transferring excess cash to vault"
  }
}

Response:

{
  "isSuccessful": true,
  "transactionId": "TXN-TILL-RMV-20251229-0001",
  "transactionState": "SETTLED",
  "message": "Cash removed from till successfully",
  "data": {
    "tillId": "TILL-002",
    "tillOwner": "John Smith",
    "amount": 200000.00,
    "transactionDate": "2025-12-29T16:30:00Z",
    "tillBalance": {
      "previousBalance": 550000.00,
      "newBalance": 350000.00,
      "minimumBalance": 50000.00,
      "availableForRemoval": 300000.00
    },
    "destinationAccount": {
      "accountKey": "VAULT-HQ-001",
      "accountType": "VAULT",
      "previousBalance": 4900000.00,
      "newBalance": 5100000.00
    },
    "impactRecords": 8
  }
}

Impact Tracking

Impacted Entities:

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

Use Cases

1. End of Day - Excess Cash to Vault:

{
  "tillId": "TILL-001",
  "amount": 300000.00,
  "destinationAccountKey": "VAULT-HQ-001",
  "removalReason": "END_OF_DAY",
  "notes": "Daily close - excess cash transfer"
}

2. Till Closure Preparation:

{
  "tillId": "TILL-003",
  "amount": 450000.00,
  "destinationAccountKey": "VAULT-HQ-001",
  "removalReason": "TILL_CLOSURE",
  "notes": "Teller leaving - closing till"
}

3. Transfer to Another Till:

{
  "tillId": "TILL-001",
  "amount": 100000.00,
  "destinationAccountKey": "TILL-004",
  "destinationType": "TILL",
  "removalReason": "TILL_TRANSFER",
  "notes": "Transfer to TILL-004 (low cash)"
}

4. Secure Transport Pickup:

{
  "tillId": "TILL-002",
  "amount": 500000.00,
  "destinationAccountKey": "GL-CASH-IN-TRANSIT",
  "destinationType": "GL",
  "removalReason": "SECURE_TRANSPORT",
  "notes": "CIT pickup - weekly deposit"
}

Error Handling

Common Errors:

Error	Reason	Resolution
`TILL_NOT_OPENED`	Till is not in OPENED state	Open till first
`INSUFFICIENT_TILL_BALANCE`	Till balance < amount	Reduce amount
`BELOW_MINIMUM_BALANCE`	Removal would leave till below minimum	Reduce amount or adjust minimum
`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

Minimum Till Balance: Each till has a minimum cash requirement (e.g., ₦50,000)
Daily Limits: May have daily removal limits for security
Authorization: Only till owner or authorized users can remove cash
Audit Trail: All cash removals fully audited with user, timestamp, destination
Physical Custody: System transaction must be accompanied by physical cash transfer
Concurrent Safety: Uses locking to prevent concurrent till modifications
Reversal: Transactions can be reversed if posted in error (see ReverseTransactionCommand)

Add Cash: AddCashToTellerTillCommand (increase till balance)
Till Transfer: TransferBetweenTellerTillCommand (move cash between tills)
Vault Transfer: TransferFromBranchVaultAccountCommand (move from vault)
Till Closure: CloseTellerTillCommand (close till and transfer all balance)

Performance Considerations

Till Locking: Uses row-level locking on till record during transaction
Transaction Time: Typically < 50ms for simple remove 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 remove cash transaction records:

✅ User who initiated transaction
✅ Timestamp of transaction
✅ Amount removed
✅ Destination of cash (vault/GL/other till)
✅ Removal reason
✅ Till owner and ID
✅ Approval details (if applicable)
✅ Before/after balances
✅ Physical custody transfer signatures

Compliance Reports

Daily Till Activity Report:

All cash removals per till
Total cash removed per teller
Destination breakdown (vault vs other)
Exception transactions (large amounts)
Below minimum balance incidents

Cash Movement Tracking:

Real-time till balance monitoring
Minimum balance breach alerts
Unusual removal pattern detection
Physical vs system balance reconciliation

Till Add Cash - Add cash to till
Till to Till Transfer - Transfer between tills
Vault to Till - Transfer from vault to till
Teller Withdrawal - Customer withdrawal via till
Teller Transactions Overview - Main transaction index

Developer Resources

For API implementation details, see:

Navigation:

Overview​

Transaction Flow​

Entities Impacted​

Scenario: Remove ₦200,000 Cash from Till to Branch Vault​

TransactionImpactRecord​

V2 API Commands​

Architecture Overview​

RemoveCashFromTellerTillCommand​

BPM Parameters​

Parameter Details​

Balance Impact​

Validation Rules​

Transaction States​

Approval Workflow​

Example Request/Response​

Impact Tracking​

Use Cases​

Error Handling​

Business Rules​

Related Operations​

Performance Considerations​

Audit and Compliance​

Audit Trail​

Compliance Reports​

Related Documentation​

Developer Resources​