Vault to Till Cash Transfer

Transfer cash from branch vault to teller till (till replenishment).

Overview

Vault to Till transfers allow branch managers to replenish teller tills from the branch vault. This operation increases till balance and decreases vault balance, typically performed at till opening or when till cash runs low.

Key Features:

Till replenishment from vault
Vault balance reduction
Till balance increase
CashManagement tracking with ADD_Cash operation
Minimum/Maximum till balance management
Concurrent transaction safety

Transaction Flow

Entities Impacted

Command: AddCashToTellerTillCommand (BPMCore)

ImpactedEntities:
[
  {
    entityType: "Vault",
    entityId: 555,
    fieldName: "Balance",
    oldValue: 500000.00,
    newValue: 450000.00,
    deltaAmount: -50000.00
  },
  {
    entityType: "Vault",
    entityId: 555,
    fieldName: "TransactionCount",
    oldValue: 15,
    newValue: 16,
    deltaAmount: +1
  },
  {
    entityType: "TellerTill",
    entityId: 789,
    fieldName: "Balance",
    oldValue: 20000.00,
    newValue: 70000.00,
    deltaAmount: +50000.00
  },
  {
    entityType: "TellerTill",
    entityId: 789,
    fieldName: "TransactionCount",
    oldValue: 42,
    newValue: 43,
    deltaAmount: +1
  },
  {
    entityType: "CashManagement",
    entityId: 888,
    fieldName: "Operation",
    oldValue: null,
    newValue: "ADD_Cash",
    deltaAmount: 0
  },
  {
    entityType: "CashManagement",
    entityId: 888,
    fieldName: "Amount",
    oldValue: 0,
    newValue: 50000.00,
    deltaAmount: +50000.00
  },
  {
    entityType: "GLAccount",
    entityKey: "1050-CASH-IN-TILL",
    fieldName: "DebitAmount",
    deltaAmount: +50000.00
  },
  {
    entityType: "GLAccount",
    entityKey: "1040-CASH-IN-VAULT",
    fieldName: "CreditAmount",
    deltaAmount: +50000.00
  }
]
```text
---

## Implementation

**BPMCore Command**: `AddCashToTellerTillCommand`

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

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

## Validation Rules

| Rule | Check | Error Message |
|------|-------|---------------|
| **Vault Exists** | Vault found | "Vault not found" |
| **Vault Active** | `VaultAccountState == OPENED` | "Vault is not active" |
| **Sufficient Cash** | `Vault.Balance >= Amount` | "Insufficient cash in vault. Available: {balance}" |
| **Till Exists** | Till found | "Till not found" |
| **Same Branch** | `Till.BranchId == Vault.BranchId` | "Till and vault must be in the same branch" |
| **Same Currency** | `Till.CurrencyId == Vault.CurrencyId` | "Currency mismatch" |
| **Maximum Balance** | `Till.Balance + Amount <= Till.MaximumBalance` (if Hard) | "Transaction will exceed till maximum balance by {excess}" |
| **Amount Valid** | `Amount > 0` | "Amount must be greater than zero" |

---

## GL Account Postings

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

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

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

## Testing

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

**Setup**:
- Vault Balance: â‚¦500,000
- Till Balance: â‚¦20,000 (low, needs replenishment)
- Transfer Amount: â‚¦50,000

**Expected Results**:

```typescript
Vault:
  Balance: 500000 â†’ 450000 âœ“
  TransactionCount: +1 âœ“

TellerTill:
  Balance: 20000 â†’ 70000 âœ“
  TransactionCount: +1 âœ“

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

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

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

**Expected Results**:

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

Vault Balance: 30000 (NO CHANGE) âœ“
Till Balance: NO CHANGE âœ“
```text
### Test Scenario 3: Till Maximum Balance Exceeded

**Setup**:
- Till Balance: â‚¦95,000
- Till MaximumBalance: â‚¦100,000
- Till Constraint: HARD
- Transfer Amount: â‚¦10,000

**Expected Results**:

```typescript
Validation:
  Error: "Transaction will exceed till maximum balance by â‚¦5,000" âœ“
  Transaction: REJECTED âœ“

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

V2 API Commands

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

Architecture Overview

The V2 vault-to-till transfer command follows the BPMCore Command Pattern:

V2 Command: TransferFromBranchVaultAccountCommand (BPMCore compatible)
BPM Integration: Accepts parameters via BpmUtil.GetPropertyValue()
Impact Tracking: Tracks both vault and till changes via TransactionImpactTracker
Atomic Operation: Both vault and till updated in single transaction
State Management: PENDING â†’ SETTLED

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

TransferFromBranchVaultAccountCommand

Purpose: Transfer cash from branch vault to teller till (till replenishment)

Command: TransferFromBranchVaultAccountCommand

Transaction State: PENDING â†’ SETTLED

BPM Parameters

{
  "commandName": "TransferFromBranchVaultAccountCommand",
  "data": {
    "vaultId": "string (mandatory)",
    "tillId": "string (mandatory)",
    "amount": "decimal (mandatory)",
    "transferReason": "string (optional)",
    "transactionDate": "DateTime (optional)",
    "notes": "string (optional)"
  }
}

Parameter Details

Parameter	Type	Required	Description
`vaultId`	string	âœ… Yes	Source vault ID
`tillId`	string	âœ… Yes	Destination till ID
`amount`	decimal	âœ… Yes	Transfer amount (must be > 0)
`transferReason`	string	âŒ No	Reason (e.g., "TILL_OPENING", "REPLENISHMENT")
`transactionDate`	DateTime	âŒ No	Transaction date (defaults to today)
`notes`	string	âŒ No	Transfer notes/remarks

Balance Impact (Atomic)

Branch Vault:

Balance Field	Change	Reason
`CashBalance`	-amount	Cash transferred to till
`AvailableBalance`	-amount	Funds withdrawn
`TransactionCount`	+1	Transaction counter

Teller Till:

Balance Field	Change	Reason
`CashBalance`	+amount	Cash received from vault
`AvailableBalance`	+amount	Funds added
`TotalCashIn`	+amount	Track inflow
`TransactionCount`	+1	Transaction counter

Validation Rules

âœ… Vault Validation:

Vault must exist and be active
Vault balance >= amount (sufficient funds)
Vault and till must be same branch
Currency must match

âœ… Till Validation:

Till must exist and be OPENED (or ready to open)
Till balance + amount must not exceed maximum till balance
Currency must match vault

Example Request/Response

Request:

{
  "commandName": "TransferFromBranchVaultAccountCommand",
  "data": {
    "vaultId": "VAULT-HQ-001",
    "tillId": "TILL-002",
    "amount": 300000.00,
    "transferReason": "TILL_OPENING",
    "transactionDate": "2025-12-29T08:30:00Z",
    "notes": "Morning till opening - float"
  }
}

Response:

{
  "isSuccessful": true,
  "transactionId": "TXN-VAULT-TILL-20251229-0001",
  "transactionState": "SETTLED",
  "message": "Cash transferred from vault to till successfully",
  "data": {
    "vaultId": "VAULT-HQ-001",
    "tillId": "TILL-002",
    "tillOwner": "John Smith",
    "amount": 300000.00,
    "transactionDate": "2025-12-29T08:30:00Z",
    "vaultBalance": {
      "previousBalance": 7000000.00,
      "newBalance": 6700000.00
    },
    "tillBalance": {
      "previousBalance": 0.00,
      "newBalance": 300000.00,
      "maximumBalance": 1000000.00
    },
    "impactRecords": 8
  }
}

Use Cases

1. Morning Till Opening:

{
  "vaultId": "VAULT-BRANCH-01",
  "tillId": "TILL-001",
  "amount": 200000.00,
  "transferReason": "TILL_OPENING",
  "notes": "Daily opening float"
}

2. Mid-Day Replenishment:

{
  "vaultId": "VAULT-BRANCH-01",
  "tillId": "TILL-003",
  "amount": 150000.00,
  "transferReason": "REPLENISHMENT",
  "notes": "Low cash alert - emergency replenishment"
}

3. Peak Hour Support:

{
  "vaultId": "VAULT-BRANCH-01",
  "tillId": "TILL-005",
  "amount": 250000.00,
  "transferReason": "PEAK_HOUR",
  "notes": "Lunch rush - additional cash"
}

Business Rules

Atomic Operation: Both vault and till updated together (all or nothing)
Same Branch: Can only transfer within same branch
Till Capacity: Cannot exceed till maximum balance
Physical Transfer: System transaction requires physical cash handover
Authorization: Typically requires branch manager or supervisor approval
Audit Trail: Full tracking of vault-to-till movement

Till to Vault: Transfer excess till cash back to vault
Vault Funding: FundBranchVaultAccountCommand (add cash to vault)
Add Cash to Till: AddCashToTellerTillCommand (same effect, different source)
Till to Till: TransferBetweenTellerTillCommand (direct till transfers)

Till to Vault Transfer - Deposit excess till cash to 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:

Vault Transactions API Reference

Overview​

Transaction Flow​

Entities Impacted​

V2 API Commands​

Architecture Overview​

TransferFromBranchVaultAccountCommand​

BPM Parameters​

Parameter Details​

Balance Impact (Atomic)​

Validation Rules​

Example Request/Response​

Use Cases​

Business Rules​

Related Operations​

Related Documentation​

Developer Resources​