Skip to main content

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​

ParameterTypeRequiredDescription
cmdstringYesMust be "FundBranchVaultAccountCommand"
dataobjectYesFunding transaction data
↳ vaultIdstringYesUnique identifier of the vault to fund
↳ amountdecimalYesAmount to add to the vault (must be positive)
↳ sourceTypestringYesSource of funds (BankTransfer, CashDeposit, InternalTransfer, OpeningBalance)
↳ sourceReferencestringNoExternal reference number
↳ narrationstringYesTransaction description
↳ transactionDatedatetimeNoTransaction 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();
}

Notes​

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

Product Documentation​

For business process and technical flow details, see: