Vault Operations Overview

Complete guide to vault operations in BankLingo V2 Core Banking Platform.

Overview

Vault operations handle cash management at the branch level, including vault funding from external sources, till replenishment, and excess cash collection. BankLingo V2 implements a robust vault transaction processing engine with:

Cash movement tracking: Every vault balance change tracked
Multi-source funding: CIT delivery, head office, bank withdrawal
Till integration: Seamless replenishment and collection
Complete audit trail: Every cash movement recorded
Reconciliation support: Physical vs. system balance verification
Universal reversal: One framework works for all transaction types

Transaction Types

Vault Operations

Transaction	Purpose	V2 Command	Key Features
Vault Funding	Fund vault from external source	`FundBranchVaultAccountCommand`	CIT delivery, head office transfer, bank withdrawal, reconciliation
Vault to Till	Replenish till from vault	`TransferFromBranchVaultAccountCommand`	Till replenishment, cash allocation, balance limits, audit trail
Till to Vault	Transfer excess cash to vault	`RemoveCashFromTellerTillCommand` (vault destination)	Cash movement, till reduction, vault increase, reconciliation

Transaction States

All vault transactions follow a state machine:

States Explained:

PENDING: Created, physical cash verification in progress
APPROVED: Verified, ready to execute
REJECTED: Denied before execution
COMPLETED: Executed, vault and till balances updated
ACTIVE: Finalized, permanent
REVERSED: Undone via compensating transaction
CANCELLED: Cancelled before completion
FAILED: Execution failed

Core Concepts

Vault Management

Each branch has a vault (secure cash storage) with:

Current Balance: Real-time cash balance
Minimum Balance: Required reserve for operations
Maximum Balance: Security/insurance limit
Currency: Assigned currency (multi-currency support)
Status: OPEN, CLOSED, SUSPENDED
Custodian: Assigned vault custodian

Vault Balance Formula:

Current Balance = Opening Balance + Funding + Till Returns - Till Disbursements

Funding Sources

Vaults can be funded from multiple sources:

Source	Description	Process
CIT (Cash-in-Transit)	Armored car delivery	Physical delivery, signature verification, count verification
Head Office Transfer	Inter-branch transfer	Electronic notification, physical transport, reconciliation
Bank Withdrawal	Withdrawal from correspondent bank	Bank counter withdrawal, receipt verification, deposit to vault
Cash Deposit	Large cash deposit to branch	Customer deposit, verification, vault storage

Cash Movement Tracking

Every vault transaction creates an audit record:

VaultTransaction {
  vaultId: "VAULT-001"
  transactionType: "FUNDING" | "TO_TILL" | "FROM_TILL"
  amount: 100000
  oldBalance: 500000
  newBalance: 600000
  source: "CIT_DELIVERY" | "HEAD_OFFICE" | "TILL-001"
  destination: "VAULT" | "TILL-001"
  physicalVerification: true
  verifiedBy: "CUSTODIAN-123"
  timestamp: "2026-01-04T08:00:00"
}

Why this matters:

Complete audit trail for high-value cash handling
Enables accurate vault reconciliation
Supports reversal and corrections
Insurance and regulatory compliance
Fraud prevention and detection

Impact Tracking

Every vault transaction records exactly what changed:

ImpactedEntity {
  entityType: "BranchVault"
  entityId: 456
  fieldName: "CurrentBalance"
  oldValue: 500000
  newValue: 600000
  deltaAmount: +100000  // The actual cash movement
}

GL Integration

All vault transactions automatically post to General Ledger:

Vault Funding Example (CIT Delivery):

DR: Vault Cash Account             +100,000
CR: Cash in Transit Account        -100,000

Vault to Till Example:

DR: Till Cash Account              +50,000
CR: Vault Cash Account             -50,000

Till to Vault Example:

DR: Vault Cash Account             +30,000
CR: Till Cash Account              -30,000

Vault Balance Limits

Maximum Balance Management

When vault balance exceeds maximum:

Alert: System notifies branch manager and vault custodian
Action Required: Transfer excess to head office or correspondent bank
Security Risk: Insurance coverage may be voided
Compliance: Regulatory reporting may be required

Minimum Balance Management

When vault balance falls below minimum:

Alert: System notifies branch manager
Action Required: Request funding (CIT, head office)
Operations Impact: Cannot adequately service tills
Planning: Schedule regular funding deliveries

Approval Workflows

Vault transactions can require approval based on:

Transaction amount (threshold)
Funding source
Time of day (after-hours)
User permissions
Vault balance thresholds

Workflow:

Initiate Vault Transaction (PENDING)
    ↓
Physical Cash Verification
    ↓
Check Approval Requirement
    ↓
Auto-Approve OR Await Approval (Branch Manager/Head Office)
    ↓
Execute Transaction (COMPLETED)
    ↓
Update Vault Balance & Related Entities

API Integration

All vault transactions are executed via BPMCore command pattern:

Endpoint:

POST /api/bpm/cmd
Content-Type: application/json
Authorization: Bearer {access_token}

Request Structure - Vault Funding:

{
  "commandName": "FundBranchVaultAccountCommand",
  "data": {
    "vaultId": "VAULT-001",
    "amount": 100000.00,
    "source": "CIT_DELIVERY",
    "referenceNumber": "CIT-2026-001",
    "notes": "Weekly CIT delivery"
  }
}

Request Structure - Vault to Till:

{
  "commandName": "TransferFromBranchVaultAccountCommand",
  "data": {
    "vaultId": "VAULT-001",
    "tillId": "TILL-001",
    "amount": 50000.00,
    "notes": "Morning till replenishment"
  }
}

Response:

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Vault transaction completed successfully",
  "data": {
    "transactionKey": "TXN-2025-001",
    "vaultId": "VAULT-001",
    "vaultBalance": {
      "previous": 500000.00,
      "current": 600000.00
    },
    "transactionState": "COMPLETED"
  }
}

Physical Reconciliation

Daily Vault Count

Physical Count: Custodian counts all cash in vault
System Balance: Retrieve current system balance
Compare: Physical vs. System
Record Variance: Any discrepancy documented
Investigation: Investigate and resolve variances

Variance Handling

Cash Short (Physical < System):

System Balance: 500,000
Physical Count: 499,500
Variance: -500 (short)

Action:
1. Recount immediately
2. Review transaction log
3. If confirmed, record variance:

GL Entry:
DR: Cash Short/Over (Expense)    +500
CR: Vault Cash Account            -500

Cash Over (Physical > System):

System Balance: 500,000
Physical Count: 500,200
Variance: +200 (over)

Action:
1. Recount immediately
2. Review transaction log
3. If confirmed, record variance:

GL Entry:
DR: Vault Cash Account            +200
CR: Cash Short/Over (Income)      -200

Security & Compliance

Dual Control

High-value vault transactions require:

Two-Person Rule: Two authorized persons present
Signature Verification: Both custodians sign
Video Surveillance: CCTV recording mandatory
Access Logs: Electronic access tracking

Regulatory Reporting

Vault operations may require reporting:

Threshold	Reporting Requirement	Authority
Large Cash Deposits	Currency Transaction Report (CTR)	Financial Intelligence Unit
Suspicious Patterns	Suspicious Activity Report (SAR)	Financial Intelligence Unit
Cross-Border	Cross-Border Cash Report	Customs/Central Bank

Concurrent Transaction Safety

BankLingo V2 ensures vault integrity in concurrent scenarios:

Optimistic Locking

Every vault has a Version field that increments with each update. Concurrent updates detected and retried.

Delta-Based Tracking

Changes tracked as deltas, not snapshots, preserving concurrent modifications.

Example Scenario

Time 08:00 - Vault Balance: 500,000
Time 08:01 - CIT Funding 100,000 PENDING
Time 08:02 - Till Replenishment 50,000 COMPLETED (balance: 450,000)
Time 08:03 - CIT Funding 100,000 COMPLETED (balance: 550,000)

Final: 550,000 ✓ (both transactions preserved)

Error Handling

All transactions use standard error codes:

Error Code	Description	Action
`00`	Success	Transaction completed
`01`	Insufficient vault cash	Request funding
`05`	Vault closed/suspended	Cannot transact
`12`	Invalid amount	Verify amount
`51`	Limit exceeded	Transfer excess to head office
`91`	System error	Retry or contact support

Best Practices

For Vault Custodians

Conduct daily physical counts
Verify all funding deliveries immediately
Keep vault organized (sort by denomination)
Report discrepancies immediately
Maintain dual control for large transactions
Follow physical security protocols strictly

For Branch Managers

Monitor vault balance daily
Schedule regular funding deliveries
Approve large transactions promptly
Investigate variances immediately
Ensure adequate cash for operations
Review audit trails regularly
Maintain insurance coverage

For Developers

Always track vault impact in transactions
Use delta-based tracking for balances
Implement proper locking mechanisms
Test concurrent transaction scenarios
Validate vault limits before execution
Log all cash movements with source/destination

Next Steps

Explore specific transaction types:

Related operations:

See Teller Transactions - Till operations
See Deposit Transactions - Customer transactions
See API Reference - Vault Transactions (./developer/)

Last Updated: January 4, 2026
Version: 2.0
Status: Production Ready

Overview​

Transaction Types​

Vault Operations​

Transaction States​

Core Concepts​

Vault Management​

Funding Sources​

Cash Movement Tracking​

Impact Tracking​

GL Integration​

Vault Balance Limits​

Maximum Balance Management​

Minimum Balance Management​

Approval Workflows​

API Integration​

Physical Reconciliation​

Daily Vault Count​

Variance Handling​

Security & Compliance​

Dual Control​

Regulatory Reporting​

Concurrent Transaction Safety​

Optimistic Locking​

Delta-Based Tracking​

Example Scenario​

Error Handling​

Best Practices​

For Vault Custodians​

For Branch Managers​

For Developers​

Next Steps​