Till to Vault Cash Transfer

Transfer excess cash from teller till to branch vault.

Overview

Till to Vault transfers allow tellers to deposit excess cash into the branch vault for safekeeping. This operation reduces till balance and increases vault balance, typically performed at end of day or when till exceeds optimal cash levels.

Key Features:

Internal cash movement (no customer involvement)
Till balance reduction
Vault balance increase
CashManagement tracking
Reconciliation support
Concurrent transaction safety

Transaction Flow

Entities Impacted

Command: RemoveCashFromTellerTillCommand (BPMCore)

ImpactedEntities:
[
  {
    entityType: "TellerTill",
    entityId: 789,
    fieldName: "Balance",
    oldValue: 150000.00,
    newValue: 100000.00,
    deltaAmount: -50000.00
  },
  {
    entityType: "TellerTill",
    entityId: 789,
    fieldName: "TransactionCount",
    oldValue: 42,
    newValue: 43,
    deltaAmount: +1
  },
  {
    entityType: "Vault",
    entityId: 555,
    fieldName: "Balance",
    oldValue: 500000.00,
    newValue: 550000.00,
    deltaAmount: +50000.00
  },
  {
    entityType: "CashManagement",
    entityId: 999,
    fieldName: "Operation",
    oldValue: null,
    newValue: "REMOVE_Cash",
    deltaAmount: 0
  },
  {
    entityType: "CashManagement",
    entityId: 999,
    fieldName: "Amount",
    oldValue: 0,
    newValue: 50000.00,
    deltaAmount: +50000.00
  },
  {
    entityType: "GLAccount",
    entityKey: "1040-CASH-IN-VAULT",
    fieldName: "DebitAmount",
    deltaAmount: +50000.00
  },
  {
    entityType: "GLAccount",
    entityKey: "1050-CASH-IN-TILL",
    fieldName: "CreditAmount",
    deltaAmount: +50000.00
  }
]
```text
---

## Implementation

**BPMCore Command**: `RemoveCashFromTellerTillCommand`

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

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

## Validation Rules

| Rule | Check | Error Message |
|------|-------|---------------|
| **Till Exists** | Till found | "Till not found" |
| **Till Opened** | `TillAccountState == OPENED` | "Till must be opened" |
| **Sufficient Cash** | `Till.Balance >= Amount` | "Insufficient cash in till. Available: {balance}" |
| **Vault Exists** | Vault found | "Vault not found" |
| **Vault Active** | `VaultAccountState == OPENED` | "Vault is not active" |
| **Same Branch** | `Till.BranchId == Vault.BranchId` | "Till and vault must be in the same branch" |
| **Same Currency** | `Till.CurrencyId == Vault.CurrencyId` | "Currency mismatch" |
| **Amount Valid** | `Amount > 0` | "Amount must be greater than zero" |

---

## GL Account Postings

| Account | Debit (Dr) | Credit (Cr) | Description |
|---------|------------|-------------|-------------|
| **Cash-in-Vault Asset** | Amount | - | Increase vault cash |
| **Cash-in-Till Asset** | - | Amount | Decrease till cash |

**Example** (â‚¦50,000 transfer):

```text
DR: 1040-Cash-in-Vault    â‚¦50,000
CR: 1050-Cash-in-Till     â‚¦50,000
```text
---

## Testing

### Test Scenario 1: Standard Till to Vault Transfer

**Setup**:
- Till Balance: â‚¦150,000
- Vault Balance: â‚¦500,000
- Transfer Amount: â‚¦50,000

**Expected Results**:

```typescript
TellerTill:
  Balance: 150000 â†’ 100000 âœ“
  TransactionCount: +1 âœ“

Vault:
  Balance: 500000 â†’ 550000 âœ“
  TransactionCount: +1 âœ“

CashManagement:
  Operation: REMOVE_Cash âœ“
  Amount: â‚¦50,000 âœ“
  TillAccountId: Set âœ“
  VaultAccountId: Set âœ“

GLEntries:
  DR: Cash-in-Vault: â‚¦50,000 âœ“
  CR: Cash-in-Till: â‚¦50,000 âœ“
```text
### Test Scenario 2: Insufficient Till Cash

**Setup**:
- Till Balance: â‚¦30,000
- Transfer Amount: â‚¦50,000

**Expected Results**:

```typescript
Validation:
  Error: "Insufficient cash in till. Available: â‚¦30,000" âœ“
  Transaction: REJECTED âœ“

Till Balance: 30000 (NO CHANGE) âœ“
Vault Balance: NO CHANGE âœ“

V2 API Commands

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

Architecture Overview

The V2 till-to-vault transfer uses the generic remove cash command with vault as destination:

V2 Command: RemoveCashFromTellerTillCommand (with vault destination)
Alternative: Can be implemented as dedicated TransferToVaultCommand if needed
BPM Integration: Accepts parameters via BpmUtil.GetPropertyValue()
Impact Tracking: Tracks both till and vault changes via TransactionImpactTracker
Atomic Operation: Both till and vault updated in single transaction

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

RemoveCashFromTellerTillCommand (to Vault)

Purpose: Transfer excess cash from teller till to branch vault

Command: RemoveCashFromTellerTillCommand

Transaction State: PENDING â†’ SETTLED

BPM Parameters

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

Parameter Details

Parameter	Type	Required	Description
`tillId`	string	âœ… Yes	Source till ID
`amount`	decimal	âœ… Yes	Transfer amount (must be > 0)
`destinationAccountKey`	string	âœ… Yes	Vault ID (destination)
`destinationType`	string	âœ… Yes	Must be "VAULT"
`removalReason`	string	âŒ No	Reason (e.g., "END_OF_DAY", "EXCESS_CASH")
`transactionDate`	DateTime	âŒ No	Transaction date (defaults to today)
`notes`	string	âŒ No	Transfer notes/remarks

Balance Impact (Atomic)

Teller Till:

Balance Field	Change	Reason
`CashBalance`	-amount	Cash transferred to vault
`AvailableBalance`	-amount	Funds withdrawn
`TotalCashOut`	+amount	Track outflow
`TransactionCount`	+1	Transaction counter

Branch Vault:

Balance Field	Change	Reason
`CashBalance`	+amount	Cash received from till
`AvailableBalance`	+amount	Funds added
`TransactionCount`	+1	Transaction counter

Validation Rules

âœ… Till Validation:

Till must exist and be OPENED
Till balance >= amount (sufficient funds)
Till balance - amount >= Minimum till balance
Till and vault must be same branch

âœ… Vault Validation:

Vault must exist and be active
Currency must match till

Example Request/Response

Request:

{
  "commandName": "RemoveCashFromTellerTillCommand",
  "data": {
    "tillId": "TILL-001",
    "amount": 400000.00,
    "destinationAccountKey": "VAULT-HQ-001",
    "destinationType": "VAULT",
    "removalReason": "END_OF_DAY",
    "transactionDate": "2025-12-29T17:00:00Z",
    "notes": "End of day - excess cash to vault"
  }
}

Response:

{
  "isSuccessful": true,
  "transactionId": "TXN-TILL-VAULT-20251229-0001",
  "transactionState": "SETTLED",
  "message": "Cash transferred from till to vault successfully",
  "data": {
    "tillId": "TILL-001",
    "tillOwner": "Jane Doe",
    "vaultId": "VAULT-HQ-001",
    "amount": 400000.00,
    "transactionDate": "2025-12-29T17:00:00Z",
    "tillBalance": {
      "previousBalance": 650000.00,
      "newBalance": 250000.00,
      "minimumBalance": 50000.00
    },
    "vaultBalance": {
      "previousBalance": 6700000.00,
      "newBalance": 7100000.00
    },
    "impactRecords": 8
  }
}

Use Cases

1. End of Day Deposit:

{
  "tillId": "TILL-002",
  "amount": 500000.00,
  "destinationAccountKey": "VAULT-BRANCH-01",
  "destinationType": "VAULT",
  "removalReason": "END_OF_DAY",
  "notes": "Daily close - excess cash deposit"
}

2. Excess Cash Management:

{
  "tillId": "TILL-003",
  "amount": 300000.00,
  "destinationAccountKey": "VAULT-BRANCH-01",
  "destinationType": "VAULT",
  "removalReason": "EXCESS_CASH",
  "notes": "Till over optimal level - transfer to vault"
}

3. Till Closure:

{
  "tillId": "TILL-005",
  "amount": 450000.00,
  "destinationAccountKey": "VAULT-BRANCH-01",
  "destinationType": "VAULT",
  "removalReason": "TILL_CLOSURE",
  "notes": "Teller leaving - closing till for day"
}

Business Rules

Atomic Operation: Both till and vault updated together (all or nothing)
Minimum Balance: Cannot leave till below minimum balance requirement
Same Branch: Can only transfer within same branch
Physical Transfer: System transaction requires physical cash handover to vault custodian
Authorization: May require supervisor approval for large amounts
Audit Trail: Full tracking of till-to-vault movement
End of Day: Typically part of daily till closing process

Vault to Till: TransferFromBranchVaultAccountCommand (replenish till)
Remove Cash from Till: RemoveCashFromTellerTillCommand (generic remove)
Till to Till: TransferBetweenTellerTillCommand (direct till transfers)
Vault Funding: FundBranchVaultAccountCommand (external vault funding)

Vault to Till Transfer - Replenish till from vault
Vault Funding - Fund vault from external source
Teller Deposit - Customer deposits increase till
Teller Withdrawal - Customer withdrawals decrease till

Developer Resources

For API implementation details, see:

Teller Transactions API Reference

Overview​

Transaction Flow​

Entities Impacted​

V2 API Commands​

Architecture Overview​

RemoveCashFromTellerTillCommand (to Vault)​

BPM Parameters​

Parameter Details​

Balance Impact (Atomic)​

Validation Rules​

Example Request/Response​

Use Cases​

Business Rules​

Related Operations​

Related Documentation​

Developer Resources​