Skip to main content

Create Branch Vault

Overview​

Creates a new vault for a specific branch to manage cash holdings and facilitate teller transactions.

Command​

CreateBranchVaultCommand

Endpoint​

POST /api/bpm/cmd

Request Headers​

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

Request Body​

{
  "cmd": "CreateBranchVaultCommand",
  "data": {
    "branchId": "BR-001",
    "vaultName": "Main Vault",
    "currencyCode": "NGN",
    "maximumBalance": 10000000.00,
    "minimumBalance": 50000.00,
    "requiresApproval": true,
    "description": "Main cash vault for branch operations"
  }
}

Request Parameters​

ParameterTypeRequiredDescription
branchIdstringYesUnique identifier of the branch where the vault will be created
vaultNamestringYesName of the vault for identification purposes
currencyCodestringYesISO currency code (e.g., "NGN", "USD", "GHS")
maximumBalancedecimalNoMaximum amount the vault can hold
minimumBalancedecimalNoMinimum balance threshold for the vault
requiresApprovalbooleanNoWhether vault transactions require approval (default: false)
descriptionstringNoAdditional information about the vault

Response​

Success Response (200 OK)​

{
  "success": true,
  "message": "Branch vault created successfully",
  "data": {
    "vaultId": "string",
    "branchId": "string",
    "vaultName": "string",
    "currencyCode": "string",
    "currentBalance": 0.00,
    "maximumBalance": "decimal",
    "minimumBalance": "decimal",
    "status": "Active",
    "createdDate": "datetime",
    "requiresApproval": "boolean"
  }
}

Error Responses​

400 Bad Request​

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "Branch ID is required",
    "Vault name is required",
    "Currency code is required"
  ]
}

404 Not Found​

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

409 Conflict​

{
  "success": false,
  "message": "Vault already exists for this branch and currency"
}

Business Rules​

  1. Each branch can have multiple vaults for different currencies
  2. Vault name must be unique within a branch
  3. Maximum balance must be greater than minimum balance if both are specified
  4. Only active branches can have vaults created
  5. Currency code must be supported by the system
  6. Initial vault balance starts at zero

Code Example​

async function createBranchVault(branchId, vaultName, currencyCode) {
  const response = await fetch('/api/bpm/cmd', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      'X-Tenant-Id': tenantId
    },
    body: JSON.stringify({
      cmd: 'CreateBranchVaultCommand',
      data: {
        branchId: branchId,
        vaultName: vaultName,
        currencyCode: currencyCode,
        maximumBalance: 10000000.00,
        minimumBalance: 50000.00,
        requiresApproval: true,
        description: 'Main cash vault for branch operations'
      }
    })
  });
  
  return await response.json();
}

Notes​

  • Vaults are essential for teller operations and cash management
  • Consider setting appropriate balance limits based on branch size and transaction volume
  • Enable approval requirements for high-security branches
  • Regular monitoring of vault balances helps prevent cash shortages