Till to Till Transfer Transaction

Transfer cash between two teller tills.

Overview

A Till to Till Transfer transaction moves cash from one teller till to another. This operation is typically used when:

• Rebalancing cash between tills (from overstocked to understocked)
• Assisting a teller with low cash
• Redistributing cash during peak hours
• Emergency cash provision to busy tellers

Key Characteristics:

• Purpose: Move cash between two tills
• Transaction Type: Till-to-till management operation
• Impact: Source till decreased, destination till increased
• Atomic Operation: Both tills updated in single transaction
• Audit: Full audit trail with both tills tracked
• Authorization: Requires authorization from both till owners or supervisor

---

Transaction Flow

---

Entities Impacted

Scenario: Transfer ₦150,000 from TILL-001 to TILL-003

Context:

• Source Till: TILL-001 (Teller: Jane Doe)
  • Current Balance: ₦450,000
  • Minimum Balance: ₦50,000
• Destination Till: TILL-003 (Teller: Alice Brown)
  • Current Balance: ₦80,000
  • Maximum Balance: ₦1,000,000
• Amount to Transfer: ₦150,000
• Reason: TILL-003 running low on cash

TransactionImpactRecord

{
  transactionId: "TXN-TILL-TRF-20251229-0001",
  transactionType: "TILL_TO_TILL_TRANSFER",
  transactionState: "SETTLED",
  transactionDate: "2025-12-29T14:15:00Z",
  amount: 150000.00,
  impactedEntities: [
    // Source Till (TILL-001) - Balance Decreased
    {
      entityType: "TellerTill",
      entityId: 101,
      entityKey: "TILL-001",
      fieldName: "CashBalance",
      oldValue: 450000.00,
      newValue: 300000.00,
      deltaAmount: -150000.00,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 101,
      entityKey: "TILL-001",
      fieldName: "AvailableBalance",
      oldValue: 450000.00,
      newValue: 300000.00,
      deltaAmount: -150000.00,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 101,
      entityKey: "TILL-001",
      fieldName: "TotalCashOut",
      oldValue: 800000.00,
      newValue: 950000.00,
      deltaAmount: +150000.00,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 101,
      entityKey: "TILL-001",
      fieldName: "TransactionCount",
      oldValue: 35,
      newValue: 36,
      deltaAmount: +1,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 101,
      entityKey: "TILL-001",
      fieldName: "LastUpdateDate",
      oldValue: "2025-12-29T13:45:00Z",
      newValue: "2025-12-29T14:15:00Z",
      deltaAmount: 0,
      isReversal: false
    },
    // Destination Till (TILL-003) - Balance Increased
    {
      entityType: "TellerTill",
      entityId: 103,
      entityKey: "TILL-003",
      fieldName: "CashBalance",
      oldValue: 80000.00,
      newValue: 230000.00,
      deltaAmount: +150000.00,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 103,
      entityKey: "TILL-003",
      fieldName: "AvailableBalance",
      oldValue: 80000.00,
      newValue: 230000.00,
      deltaAmount: +150000.00,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 103,
      entityKey: "TILL-003",
      fieldName: "TotalCashIn",
      oldValue: 400000.00,
      newValue: 550000.00,
      deltaAmount: +150000.00,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 103,
      entityKey: "TILL-003",
      fieldName: "TransactionCount",
      oldValue: 28,
      newValue: 29,
      deltaAmount: +1,
      isReversal: false
    },
    {
      entityType: "TellerTill",
      entityId: 103,
      entityKey: "TILL-003",
      fieldName: "LastUpdateDate",
      oldValue: "2025-12-29T13:30:00Z",
      newValue: "2025-12-29T14:15:00Z",
      deltaAmount: 0,
      isReversal: false
    },
    // GL Accounts (Internal Till Transfer)
    {
      entityType: "GLAccount",
      entityKey: "1100-TILL-003",  // Destination Till GL
      fieldName: "DebitAmount",
      deltaAmount: +150000.00
    },
    {
      entityType: "GLAccount",
      entityKey: "1100-TILL-001",  // Source Till GL
      fieldName: "CreditAmount",
      deltaAmount: +150000.00
    }
  ]
}

---

V2 API Commands

BankLingo V2 provides a BPMCore-compatible command for till-to-till transfers.

Architecture Overview

The V2 till transfer command follows the BPMCore Command Pattern:

• V2 Command: TransferBetweenTellerTillCommand (BPMCore compatible)
• BPM Integration: Accepts parameters via BpmUtil.GetPropertyValue()
• Impact Tracking: Full impact tracking for both tills via TransactionImpactTracker
• Atomic Operation: Both till updates in single transaction (all or nothing)
• State Management: PENDING → APPROVED → SETTLED
• Approval Workflow: Configurable approval thresholds

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

---

TransferBetweenTellerTillCommand

Purpose: Transfer cash between two teller tills atomically

Command: TransferBetweenTellerTillCommand

Transaction State: PENDING → SETTLED

BPM Parameters

{
  "commandName": "TransferBetweenTellerTillCommand",
  "data": {
    "sourceTillId": "string (mandatory)",
    "destinationTillId": "string (mandatory)",
    "amount": "decimal (mandatory)",
    "transferReason": "string (optional)",
    "transactionDate": "DateTime (optional)",
    "notes": "string (optional)"
  }
}

Parameter Details

Parameter	Type	Required	Description
sourceTillId	string	✅ Yes	Source teller till ID (cash withdrawn from)
destinationTillId	string	✅ Yes	Destination teller till ID (cash added to)
amount	decimal	✅ Yes	Cash amount to transfer (must be > 0)
transferReason	string	❌ No	Reason code (e.g., "LOW_CASH", "REBALANCE")
transactionDate	DateTime	❌ No	Transaction date (defaults to today)
notes	string	❌ No	Transaction notes/remarks

Balance Impact (Atomic)

Source Till:

Balance Field	Change	Reason
CashBalance	-amount	Cash transferred out
AvailableBalance	-amount	Funds withdrawn
TotalCashOut	+amount	Track total outflow
TransactionCount	+1	Transaction counter
LastUpdateDate	Set to now	Track last update

Destination Till:

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

⚠️ ATOMIC: Both till updates occur in single database transaction - either both succeed or both fail.

Validation Rules

✅ Till Validation:

• Both tills must exist
• Both tills must be in OPENED state
• Tills must be different (cannot transfer to same till)
• User must be authorized for till operations
• Source till: Current balance >= amount (sufficient funds)
• Source till: Current balance - amount >= Minimum balance
• Destination till: Current balance + amount <= Maximum balance

✅ Amount Validation:

• Amount must be > 0
• Amount must not leave source till below minimum
• Amount must not exceed destination till maximum
• Both tills must have same currency

❌ Rejection Scenarios:

• Either till not found or not opened
• Tills are the same (source = destination)
• Insufficient source till balance
• Amount would leave source till below minimum
• Amount would exceed destination till maximum
• User not authorized
• Either till locked or suspended
• Currency mismatch between tills

Transaction States

States:

1. PENDING: Transaction initiated, awaiting approval (if required)
2. APPROVED: Approved, ready for execution
3. SETTLED: Cash transferred, both till balances updated atomically
4. REJECTED: Transaction rejected (no balance changes)

Approval Workflow

• ✅ Auto-approval if amount < configured limit (e.g., ₦100,000)
• ⚠️ Manual approval required if amount ≥ limit
• 🔒 Amount placed on hold on source till during approval
• 🔓 Hold released on rejection
• 📧 Both till owners notified of approval requirement

Example Request/Response

Request:

{
  "commandName": "TransferBetweenTellerTillCommand",
  "data": {
    "sourceTillId": "TILL-001",
    "destinationTillId": "TILL-003",
    "amount": 150000.00,
    "transferReason": "LOW_CASH",
    "transactionDate": "2025-12-29T14:15:00Z",
    "notes": "TILL-003 running low - emergency transfer from TILL-001"
  }
}

Response:

{
  "isSuccessful": true,
  "transactionId": "TXN-TILL-TRF-20251229-0001",
  "transactionState": "SETTLED",
  "message": "Till to till transfer completed successfully",
  "data": {
    "sourceTillId": "TILL-001",
    "sourceTillOwner": "Jane Doe",
    "destinationTillId": "TILL-003",
    "destinationTillOwner": "Alice Brown",
    "amount": 150000.00,
    "transactionDate": "2025-12-29T14:15:00Z",
    "sourceTillBalance": {
      "previousBalance": 450000.00,
      "newBalance": 300000.00,
      "minimumBalance": 50000.00,
      "availableForTransfer": 250000.00
    },
    "destinationTillBalance": {
      "previousBalance": 80000.00,
      "newBalance": 230000.00,
      "maximumBalance": 1000000.00,
      "remainingCapacity": 770000.00
    },
    "impactRecords": 12
  }
}

Impact Tracking (Dual Till)

Impacted Entities:

• ✅ Source Till (5 field changes: cash balance, available balance, total cash out, transaction count, last update)
• ✅ Destination Till (5 field changes: cash balance, available balance, total cash in, transaction count, last update)
• ✅ GL Accounts (journal entries for inter-till transfer)

Critical: Each till's changes are tracked separately in impact records

Use Cases

1. Emergency Cash Support:

{
  "sourceTillId": "TILL-001",
  "destinationTillId": "TILL-004",
  "amount": 200000.00,
  "transferReason": "EMERGENCY_SUPPORT",
  "notes": "TILL-004 busy counter - urgent cash needed"
}

2. Daily Till Rebalancing:

{
  "sourceTillId": "TILL-002",
  "destinationTillId": "TILL-005",
  "amount": 100000.00,
  "transferReason": "REBALANCE",
  "notes": "Balance tills - TILL-002 overstocked, TILL-005 understocked"
}

3. Peak Hour Redistribution:

{
  "sourceTillId": "TILL-003",
  "destinationTillId": "TILL-001",
  "amount": 75000.00,
  "transferReason": "PEAK_HOUR",
  "notes": "Lunch rush - TILL-001 needs more cash"
}

4. Till Consolidation:

{
  "sourceTillId": "TILL-006",
  "destinationTillId": "TILL-001",
  "amount": 300000.00,
  "transferReason": "CONSOLIDATION",
  "notes": "TILL-006 closing early - consolidate to TILL-001"
}

Error Handling

Common Errors:

Error	Reason	Resolution
TILL_NOT_OPENED	One or both tills not in OPENED state	Open both tills first
SAME_TILL_TRANSFER	Source and destination are same till	Use different tills
INSUFFICIENT_SOURCE_BALANCE	Source till balance < amount	Reduce amount or use different source
SOURCE_BELOW_MINIMUM	Transfer would leave source below minimum	Reduce amount
DESTINATION_EXCEEDS_MAXIMUM	Transfer would exceed destination maximum	Reduce amount or increase destination limit
UNAUTHORIZED_USER	User not authorized for either till	Use authorized user or supervisor
CURRENCY_MISMATCH	Tills have different currencies	Cannot transfer between different currencies

Business Rules

1. Atomic Operation: Both till updates must succeed or both fail (no partial transfer)
2. Balance Constraints: Must respect both source minimum and destination maximum
3. Authorization: Requires authorization from both till owners or supervisor approval
4. Physical Transfer: System transaction must be accompanied by physical cash handover
5. Audit Trail: Both tills tracked in single transaction with complete audit trail
6. Concurrent Safety: Uses locking on both tills to prevent race conditions
7. Currency Matching: Can only transfer between tills with same currency
8. Reversal: Transactions can be reversed if posted in error (see ReverseTransactionCommand)

Related Operations

• Add Cash to Till: AddCashToTellerTillCommand (add cash from vault)
• Remove Cash from Till: RemoveCashFromTellerTillCommand (remove to vault)
• Vault to Till: TransferFromBranchVaultAccountCommand (vault → till)
• Till to Vault: Transfer cash to vault for safekeeping

---

Performance Considerations

• Dual Till Locking: Uses row-level locking on BOTH till records during transaction
• Transaction Time: Typically < 100ms for dual-till atomic operation
• Impact Records: Creates 10-15 impact entries per transaction (both tills tracked)
• Concurrent Operations: Serialized per till pair to prevent race conditions
• Validation: All validations (both tills) complete before any balance changes
• Rollback: Automatic rollback if either till update fails

---

Audit and Compliance

Audit Trail

Every till-to-till transfer records:

• ✅ User who initiated transaction
• ✅ Timestamp of transaction
• ✅ Amount transferred
• ✅ Source till (owner, ID, before/after balance)
• ✅ Destination till (owner, ID, before/after balance)
• ✅ Transfer reason
• ✅ Approval details (if applicable)
• ✅ Physical custody transfer signatures from both tellers

Compliance Reports

Daily Till Transfer Report:

• All till-to-till transfers
• Transfer frequency per till pair
• Total amount transferred per till
• Exception transactions (large amounts, frequent transfers)
• Balance movement patterns

Till Network Analysis:

• Cash flow between tills (source/destination patterns)
• Identify tills that frequently need cash
• Identify tills that frequently have excess
• Optimize daily till opening balances

---

Related Documentation

• Till Add Cash - Add cash to till
• Till Remove Cash - Remove cash from till
• Vault to Till - Transfer from vault to till
• Vault Funding - Add cash to branch vault
• Teller Transactions Overview - Main transaction index

---

Developer Resources

For API implementation details, see:

• Transfer Between Tills API - Developer Guide
• Till Accounts API Reference

---

Navigation:

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