Transfer From Branch Vault Account

Overview

Transfers or withdraws funds from a branch vault to another destination (teller till, another vault, or external account).

Command

TransferFromBranchVaultAccountCommand

Endpoint

POST /api/bpm/cmd

Request Headers

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

Request Body

{
  "cmd": "TransferFromBranchVaultAccountCommand",
  "data": {
    "vaultId": "VLT-001",
    "amount": 500000.00,
    "destinationType": "TellerTill",
    "destinationId": "TILL-T001",
    "narration": "Daily till funding for Teller 1",
    "transactionDate": "2024-01-15T08:00:00Z",
    "requiresApproval": false
  }
}

Request Parameters

Parameter	Type	Required	Description
cmd	string	Yes	Must be "TransferFromBranchVaultAccountCommand"
data	object	Yes	Transfer transaction data
↳ vaultId	string	Yes	Unique identifier of the source vault
↳ amount	decimal	Yes	Amount to transfer (must be positive)
↳ destinationType	string	Yes	Destination type (TellerTill, AnotherVault, ExternalAccount, BankAccount)
↳ destinationId	string	Yes	Identifier of destination (till ID, vault ID, or account number)
↳ narration	string	Yes	Description of the transfer transaction
↳ transactionDate	datetime	No	Transaction date (defaults to current date/time)
↳ requiresApproval	boolean	No	Whether transfer requires approval (default: false)

• Type: string
• Required: Yes
• Description: Description of the transfer transaction

transactionDate

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

requiresApproval

• Type: boolean
• Required: No
• Default: Based on vault configuration
• Description: Whether the transfer requires approval

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Transfer completed successfully",
  "data": {
    "transactionId": "string",
    "vaultId": "string",
    "destinationType": "string",
    "destinationId": "string",
    "amount": "decimal",
    "previousBalance": "decimal",
    "newBalance": "decimal",
    "transactionDate": "datetime",
    "status": "Completed",
    "narration": "string",
    "approvalRequired": "boolean"
  }
}

Error Responses

400 Bad Request

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

404 Not Found

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

409 Conflict

{
  "success": false,
  "message": "Insufficient vault balance for transfer"
}

Business Rules

1. Amount must be positive and non-zero
2. Vault must have sufficient balance
3. Transfer cannot reduce balance below minimum threshold
4. Destination must be active and accessible
5. Currency must match between source and destination
6. Large transfers may require supervisor approval
7. Transaction creates audit trail entries for both source and destination

Code Example

async function transferFromVault(vaultId, amount, destinationType, destinationId, 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: 'TransferFromBranchVaultAccountCommand',
      data: {
        vaultId: vaultId,
        amount: amount,
        destinationType: destinationType,
        destinationId: destinationId,
        narration: narration,
        transactionDate: new Date().toISOString()
      }
    })
  });
  
  return await response.json();
}

Related Commands

• Fund Branch Vault Account - Add funds to vault
• Get Branch Vault List - View vault balances
• Open Teller Till - Create teller till

Notes

• Verify sufficient balance before initiating transfers
• Monitor minimum balance thresholds to maintain liquidity
• Keep detailed records of all vault transfers for audit purposes
• Consider approval workflows for high-value transfers
• Ensure currency compatibility between source and destination