Transfer From Branch Vault Account

Overview

Processes a transfer or withdrawal transaction from a branch vault to another destination.

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": "Morning till allocation",
    "transactionDate": "2024-12-18T08: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	Type of destination (TellerTill, AnotherVault, ExternalAccount, BankAccount)
↳ destinationId	string	Yes	Identifier of the destination
↳ narration	string	Yes	Transaction description
↳ transactionDate	datetime	No	Transaction timestamp (defaults to current time)
↳ requiresApproval	boolean	No	Whether transaction requires approval (default: false)

• Type: string
• Required: Yes
• Description: Transaction description

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

Error Responses

400 Bad Request

{
  "success": false,
  "message": "Validation failed",
  "errors": ["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"
}

Business Rules

1. Amount must be positive and non-zero
2. Vault must have sufficient balance
3. Cannot reduce balance below minimum threshold
4. Destination must be active
5. Currency must match between source and destination
6. Large transfers may require approval

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

Related Commands

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

Notes

• Verify sufficient balance before transfers
• Monitor minimum balance thresholds
• Document all transfers for audit purposes
• Consider approval workflows for high-value transfers