Vault Funding Transaction

Fund branch vault from external source (CIT company, Head Office, Bank transfer).

Overview

Vault funding transactions allow branch managers to increase vault cash balances from external sources such as Cash-In-Transit (CIT) companies, head office transfers, or bank deposits. This is the primary mechanism for injecting cash into the branch cash management ecosystem.

Key Features:

• External cash injection to vault
• Multiple funding sources (CIT, Head Office, Bank Transfer)
• Vault balance increase
• No till involvement (direct to vault)
• Reconciliation with external records
• Concurrent transaction safety

---

Transaction Flow

---

Entities Impacted

Command: FundBranchVaultAccountCommand

CIT Funding Scenario

ImpactedEntities:
[
  {
    entityType: "Vault",
    entityId: 555,
    fieldName: "Balance",
    oldValue: 500000.00,
    newValue: 1500000.00,
    deltaAmount: +1000000.00
  },
  {
    entityType: "Vault",
    entityId: 555,
    fieldName: "TransactionCount",
    oldValue: 15,
    newValue: 16,
    deltaAmount: +1
  },
  {
    entityType: "VaultFunding",
    entityId: 777,
    fieldName: "FundingSource",
    oldValue: null,
    newValue: "CIT",
    deltaAmount: 0
  },
  {
    entityType: "VaultFunding",
    entityId: 777,
    fieldName: "Amount",
    oldValue: 0,
    newValue: 1000000.00,
    deltaAmount: +1000000.00
  },
  {
    entityType: "VaultFunding",
    entityId: 777,
    fieldName: "ExternalReference",
    oldValue: null,
    newValue: "CIT-2025-001234",
    deltaAmount: 0
  },
  {
    entityType: "GLAccount",
    entityKey: "1040-CASH-IN-VAULT",
    fieldName: "DebitAmount",
    deltaAmount: +1000000.00
  },
  {
    entityType: "GLAccount",
    entityKey: "2100-CIT-SUSPENSE",
    fieldName: "CreditAmount",
    deltaAmount: +1000000.00
  }
]
```text
---

## Implementation

**Command**: `FundBranchVaultAccountCommand`

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

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

## Funding Sources

### 1. CIT (Cash-In-Transit) Company

**Use Case**: External cash delivery service

**GL Posting**:

```text
DR: 1040-Cash-in-Vault           ₦1,000,000
CR: 2100-CIT-Suspense            ₦1,000,000
```text
**Reconciliation**: When CIT invoice received, clear suspense account

### 2. Head Office Transfer

**Use Case**: Internal cash transfer from head office

**GL Posting**:

```text
DR: 1040-Cash-in-Vault           ₦500,000
CR: 2200-Head-Office-Account     ₦500,000
```text
**Reconciliation**: Automatic via inter-branch settlement

### 3. Bank Transfer

**Use Case**: Cash withdrawal from bank account

**GL Posting**:

```text
DR: 1040-Cash-in-Vault           ₦200,000
CR: 1010-Bank-Account            ₦200,000
```text
**Reconciliation**: Match with bank statement

---

## Validation Rules

| Rule | Check | Error Message |
|------|-------|---------------|
| **Vault Exists** | Vault found | "Vault not found" |
| **Vault Active** | `VaultAccountState == OPENED` | "Vault is not active" |
| **Amount Valid** | `Amount > 0` | "Amount must be greater than zero" |
| **External Reference** | Reference provided | "External reference is required" |
| **No Duplicate** | Reference not used | "Duplicate external reference: {reference}" |
| **Funding Source** | Valid source enum | "Invalid funding source" |

---

## GL Account Postings

| Account | Debit (Dr) | Credit (Cr) | Description |
|---------|------------|-------------|-------------|
| **Cash-in-Vault Asset** | Amount | - | Increase vault cash |
| **External Source** | - | Amount | CIT Suspense / Head Office / Bank Account |

---

## Testing

### Test Scenario 1: CIT Funding

**Setup**:
- Vault Balance: ₦500,000
- CIT Delivery: ₦1,000,000
- External Reference: CIT-2025-001234

**Expected Results**:

```typescript
Vault:
  Balance: 500000 → 1500000 ✓
  TransactionCount: +1 ✓

VaultFunding:
  FundingSource: CIT ✓
  Amount: ₦1,000,000 ✓
  ExternalReference: "CIT-2025-001234" ✓
  Status: COMPLETED ✓

GLEntries:
  DR: Cash-in-Vault: ₦1,000,000 ✓
  CR: CIT-Suspense: ₦1,000,000 ✓
```text
### Test Scenario 2: Duplicate Reference

**Setup**:
- Previous Funding: CIT-2025-001234 already exists
- New Funding: Same reference CIT-2025-001234

**Expected Results**:

```typescript
Validation:
  Error: "Duplicate external reference: CIT-2025-001234" ✓
  Transaction: REJECTED ✓

Vault Balance: NO CHANGE ✓
```text
---

## Reconciliation Process

### CIT Reconciliation

1. **Receive Cash**: Physical cash delivered by CIT
2. **Record Funding**: `FundBranchVaultAccountCommand` executed
3. **Receive Invoice**: CIT company sends invoice
4. **Match Records**: Compare funding record with invoice
5. **Clear Suspense**: Post journal entry to clear suspense

```text
DR: 2100-CIT-Suspense            ₦1,000,000
CR: 2300-CIT-Payable             ₦1,000,000
```text
### Head Office Reconciliation

1. **Request Funding**: Branch requests cash from head office
2. **Approve Transfer**: Head office approves
3. **Record Funding**: `FundBranchVaultAccountCommand` executed
4. **Auto-Settlement**: Inter-branch settlement automatically reconciles

### Bank Transfer Reconciliation

1. **Withdraw from Bank**: Branch manager withdraws from bank
2. **Record Funding**: `FundBranchVaultAccountCommand` executed
3. **Bank Statement**: Receive bank statement
4. **Match Transaction**: Compare with bank records

---

## V2 API Commands

BankLingo V2 provides a BPMCore-compatible command for vault funding operations.

### Architecture Overview

The V2 vault funding command follows the **BPMCore Command Pattern**:

- **V2 Command**: `FundBranchVaultAccountCommand` (BPMCore compatible)
- **BPM Integration**: Accepts parameters via `BpmUtil.GetPropertyValue()`
- **Impact Tracking**: Full impact tracking via `TransactionImpactTracker`
- **State Management**: PENDING → SETTLED
- **External Reconciliation**: Links to external funding sources

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

---

### FundBranchVaultAccountCommand

**Purpose**: Fund branch vault from external source (increase vault cash balance)

**Command**: `FundBranchVaultAccountCommand`

**Transaction State**: PENDING → SETTLED

#### BPM Parameters

```json
{
  "commandName": "FundBranchVaultAccountCommand",
  "data": {
    "vaultId": "string (mandatory)",
    "amount": "decimal (mandatory)",
    "fundingSource": "string (optional)",
    "externalReference": "string (optional)",
    "transactionDate": "DateTime (optional)",
    "notes": "string (optional)"
  }
}

Parameter Details

Parameter	Type	Required	Description
vaultId	string	✅ Yes	Branch vault ID to fund
amount	decimal	✅ Yes	Funding amount (must be > 0)
fundingSource	string	❌ No	Source type (e.g., "CIT", "HEAD_OFFICE", "BANK_TRANSFER")
externalReference	string	❌ No	External reference (CIT reference, transfer ID)
transactionDate	DateTime	❌ No	Funding date (defaults to today)
notes	string	❌ No	Funding notes/remarks

Balance Impact

Branch Vault:

Balance Field	Change	Reason
CashBalance	+amount	Vault funded
AvailableBalance	+amount	Available for till replenishment
TotalFunding	+amount	Track total inflow
TransactionCount	+1	Transaction counter
LastUpdateDate	Set to now	Track last update

GL Accounts:

Account	Debit/Credit	Amount	Description
Cash-in-Vault	Debit	+amount	Increase vault asset
External Source	Credit	+amount	CIT suspense/Head office/Bank account

Validation Rules

✅ Vault Validation:

• Vault must exist and be active
• Vault must not be locked or suspended
• Amount currency must match vault currency

✅ Amount Validation:

• Amount must be > 0
• No maximum limit (vaults can hold large amounts)

✅ Source Validation (if specified):

• External reference should be provided for audit
• Funding source should be valid type

Example Request/Response

Request:

{
  "commandName": "FundBranchVaultAccountCommand",
  "data": {
    "vaultId": "VAULT-HQ-001",
    "amount": 5000000.00,
    "fundingSource": "CIT",
    "externalReference": "CIT-2025-001234",
    "transactionDate": "2025-12-29T08:00:00Z",
    "notes": "Weekly CIT delivery - G4S"
  }
}

Response:

{
  "isSuccessful": true,
  "transactionId": "TXN-VAULT-FUND-20251229-0001",
  "transactionState": "SETTLED",
  "message": "Vault funded successfully",
  "data": {
    "vaultId": "VAULT-HQ-001",
    "branchName": "Head Office",
    "amount": 5000000.00,
    "fundingSource": "CIT",
    "externalReference": "CIT-2025-001234",
    "transactionDate": "2025-12-29T08:00:00Z",
    "vaultBalance": {
      "previousBalance": 2000000.00,
      "newBalance": 7000000.00,
      "totalFunding": 50000000.00
    },
    "impactRecords": 6
  }
}

Impact Tracking

Impacted Entities:

• ✅ Branch Vault (5 field changes: cash balance, available balance, total funding, transaction count, last update)
• ✅ GL Accounts (2 entries: vault DR, external source CR)
• ✅ Vault Funding Record (external reference tracking)

Use Cases

1. CIT Delivery:

{
  "vaultId": "VAULT-BRANCH-05",
  "amount": 10000000.00,
  "fundingSource": "CIT",
  "externalReference": "G4S-2025-W52-001",
  "notes": "Weekly CIT delivery - G4S"
}

2. Head Office Transfer:

{
  "vaultId": "VAULT-BRANCH-02",
  "amount": 3000000.00,
  "fundingSource": "HEAD_OFFICE",
  "externalReference": "HO-TRF-20251229-045",
  "notes": "Inter-branch transfer from HO"
}

3. Bank Transfer Credit:

{
  "vaultId": "VAULT-BRANCH-10",
  "amount": 2500000.00,
  "fundingSource": "BANK_TRANSFER",
  "externalReference": "BANK-DEP-20251229-789",
  "notes": "Bank deposit for vault replenishment"
}

Business Rules

1. No Maximum Limit: Vaults can hold large amounts (unlike tills with maximum balance)
2. External Reconciliation: All fundings should have external reference for reconciliation
3. Audit Trail: Full audit trail with funding source, reference, and amount
4. Physical Verification: System funding should be verified with physical cash count
5. GL Integration: Automatic GL posting to vault and external source accounts
6. No Approval Required: Vault fundings typically auto-approved (external funds already verified)

Related Operations

• Vault to Till: TransferFromBranchVaultAccountCommand (distribute to tills)
• Till to Vault: Transfer excess till cash back to vault
• Add Cash to Till: AddCashToTellerTillCommand (ultimate destination of vault cash)

---

Related Documentation

• Vault to Till Transfer - Replenish till from funded vault
• Till to Vault Transfer - Deposit excess till cash to vault
• Teller Deposit - Customer deposits increase till
• Transaction Impact Tracking - Delta-based tracking system

---

Developer Resources

For API implementation details, see:

• Vault Transactions API Reference

---