Fund Branch Vault Account

Overview

Adds funds to a branch vault account from an external source or internal transfer.

Command

FundBranchVaultAccountCommand

Endpoint

POST /api/bpm/cmd

Request Headers

Authorization: Bearer {access_token}
Content-Type: application/json
X-Tenant-Id: {tenant_id}

Request Body

{
  "cmd": "FundBranchVaultAccountCommand",
  "data": {
    "vaultId": "VLT-001",
    "amount": 1000000.00,
    "sourceType": "BankTransfer",
    "sourceReference": "TXN-2024-001234",
    "narration": "Daily vault funding from head office",
    "transactionDate": "2024-01-15T09:00:00Z"
  }
}

Request Parameters

Parameter	Type	Required	Description
cmd	string	Yes	Must be "FundBranchVaultAccountCommand"
data	object	Yes	Funding transaction data
↳ vaultId	string	Yes	Unique identifier of the vault to fund
↳ amount	decimal	Yes	Amount to add to the vault (must be positive)
↳ sourceType	string	Yes	Source of funds (BankTransfer, CashDeposit, InternalTransfer, OpeningBalance)
↳ sourceReference	string	No	External reference number (e.g., bank transfer reference)
↳ narration	string	Yes	Description of the funding transaction
↳ transactionDate	datetime	No	Transaction date (defaults to current date/time)

• Required: Yes
• Description: Description of the funding transaction

transactionDate

• Type: datetime
• Required: No
• Default: Current date/time
• Description: Date and time of the transaction

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Vault funded successfully",
  "data": {
    "transactionId": "string",
    "vaultId": "string",
    "amount": "decimal",
    "previousBalance": "decimal",
    "newBalance": "decimal",
    "sourceType": "string",
    "sourceReference": "string",
    "transactionDate": "datetime",
    "status": "Completed",
    "narration": "string"
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "Vault ID is required",
    "Amount must be greater than zero",
    "Narration is required"
  ]
}

404 Not Found

{
  "success": false,
  "message": "Vault not found with the provided ID"
}

409 Conflict

{
  "success": false,
  "message": "Funding exceeds maximum vault balance limit"
}

Business Rules

1. Amount must be positive and non-zero
2. Funding cannot exceed maximum vault balance
3. Vault must be in "Active" status
4. Transaction creates an audit trail entry
5. Source reference is mandatory for external transfers
6. Duplicate source references are rejected within 24 hours
7. Large amounts may require additional approval

Code Example

async function fundBranchVault(vaultId, amount, narration) {
  const response = await fetch('/api/bpm/cmd', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      'X-Tenant-Id': tenantId
    },
    body: JSON.stringify({
      commandType: 'FundBranchVaultAccountCommand',
      data: {
        vaultId: vaultId,
        amount: amount,
        sourceType: 'BankTransfer',
        sourceReference: 'BT-2024-001234',
        narration: narration,
        transactionDate: new Date().toISOString()
      }
    })
  });
  
  return await response.json();
}

Related Commands

• Transfer From Branch Vault Account - Remove funds
• Get Branch Vault List - View vault balances
• Update Branch Vault - Modify vault limits

Notes

• Verify vault balance limits before funding large amounts
• Keep source references for reconciliation purposes
• Schedule regular vault funding to maintain adequate cash levels
• Monitor vault balances to avoid exceeding maximum limits
• Document all funding transactions for audit compliance