Fund Branch Vault Account

Overview

Processes a fund addition transaction to a branch vault account, adding cash to the vault balance.

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 replenishment",
    "transactionDate": "2024-12-18T10: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
↳ narration	string	Yes	Transaction description
↳ transactionDate	datetime	No	Transaction timestamp (defaults to current time)

• Required: Yes
• Description: Transaction description

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"
  }
}

Error Responses

400 Bad Request

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

404 Not Found

{
  "success": false,
  "message": "Vault not found"
}

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. Creates audit trail entry
5. Source reference mandatory for external transfers

Code Example

async function fundVault(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
      }
    })
  });
  
  return await response.json();
}

Related Commands

• Transfer From Branch Vault Account - Remove funds
• Vault Management Overview - Vault setup

Notes

• Verify vault balance limits before funding
• Keep source references for reconciliation
• Document all transactions for audit compliance