Deposit Account Transactions Overview

Complete guide to deposit account transactions in BankLingo V2 Core Banking Platform.

Overview

Deposit account transactions enable deposits, withdrawals, and transfers for all deposit account types. BankLingo V2 implements a robust transaction processing engine with:

• Delta-based impact tracking: Every field change tracked for accurate reversal
• Multi-phase processing: PENDING → APPROVED → COMPLETED → ACTIVE
• Hold management: Prevents overdraft in concurrent scenarios
• Concurrent safety: Optimistic locking + delta-based reversal
• Complete audit trail: Every entity impact recorded
• Universal reversal: One framework works for all transaction types

---

Deposit Account Types

All deposit transactions are performed on product-based accounts. BankLingo V2 supports the following deposit account types:

Enum: DepositAccountTypeEnum

Type	Description	Typical Use
Current_Account	Transactional account with no interest	Business operations, frequent transactions
Savings_Account	Interest-bearing savings account	Personal savings with withdrawals
Fixed_Deposit	Locked deposit for fixed term	Investment with higher interest rates
Savings_Plan	Goal-based savings with rules	Planned savings for specific targets
Funding_Account	Internal funding and settlement account	Branch operations, CIT

Note: Each account type has its own configuration in the DepositProduct entity, including limits, fees, interest rates, and transaction rules.

---

Transaction Types

Core Deposit Transactions

Transaction	Purpose	V2 Command	Key Features
Deposit	Credit funds to account	InitiateDepositCommand	Teller/Channel deposits, approval workflow, account activation
Withdrawal	Debit funds from account	InitiateWithdrawalCommand	Hold management, concurrent safety, till/settlement impact
Transfer	Move funds between accounts	InitiateTransferCommand	Atomic operations, deadlock prevention, intra/inter-bank

---

Transaction States

All deposit transactions follow a state machine:

States Explained:

• PENDING: Created, may require approval, holds may be placed
• APPROVED: Approved, ready to execute
• REJECTED: Denied before execution
• COMPLETED: Executed, balances updated
• ACTIVE: Finalized, permanent
• REVERSED: Undone via compensating transaction
• CANCELLED: Cancelled before completion
• FAILED: Execution failed

---

Core Concepts

Impact Tracking

Every transaction records exactly what changed:

ImpactedEntity {
  entityType: "DepositAccount"
  entityId: 12345
  fieldName: "BookBalance"
  oldValue: 100000
  newValue: 105000
  deltaAmount: +5000  // The actual change
}

Why this matters:

• Enables accurate reversal even with concurrent transactions
• Complete audit trail of all changes
• Supports multi-entity transactions
• Preserves data integrity

Hold Management

Withdrawals and transfers use hold management to prevent overdraft:

Two Balance Types:

• BookBalance: Actual ledger balance
• AvailableBalance: BookBalance - HoldAmount

Process:

1. PENDING: Place hold (AvailableBalance reduced immediately)
2. COMPLETED: Deduct BookBalance, release hold
3. REJECTED: Release hold, restore AvailableBalance

This prevents concurrent transactions from overdrawing the account.

GL Integration

All transactions automatically post to General Ledger using double-entry accounting:

Deposit Example:

DR: Cash/Till/Settlement    +5,000
CR: Customer Deposits       -5,000

Withdrawal Example:

DR: Customer Deposits       +5,000
CR: Cash/Till/Settlement    -5,000

---

Transaction Limits

All deposit transactions respect configured limits:

Limit Type	Description	Enforcement
Single Transaction	Maximum per transaction	Pre-validation
Daily Cumulative	Maximum per day	Real-time check
Account Balance	Maximum account balance	Pre-credit check
Transaction Count	Maximum transactions per day	Counter check

Exceeded Limit Behavior:

• Transaction rejected with specific error code
• Option to place on PND (Pending - Not Drawn)
• Notification to account officer
• Audit trail created

---

Approval Workflows

Transactions can require approval based on:

• Transaction amount (threshold)
• Account type
• Channel type
• User permissions
• Product configuration

Workflow:

Create Transaction (PENDING)
    ↓
Check Approval Requirement
    ↓
Auto-Approve OR Await Approval
    ↓
Execute Transaction (COMPLETED)

---

API Integration

All deposit transactions are executed via BPMCore command pattern:

Endpoint:

POST /api/bpm/cmd
Content-Type: application/json
Authorization: Bearer {access_token}

Request Structure:

{
  "commandName": "InitiateDepositCommand",
  "data": {
    "accountEncodedKey": "ACC-001",
    "amount": 5000.00,
    "channelCode": "TELLER",
    "notes": "Cash deposit"
  }
}

Response:

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Transaction completed successfully",
  "data": {
    "transactionKey": "TXN-2025-001",
    "accountNumber": "1234567890",
    "transactionState": "COMPLETED"
  }
}

---

Concurrent Transaction Safety

BankLingo V2 ensures data integrity in concurrent scenarios:

Optimistic Locking

Every account has a Version field that increments with each update. Concurrent updates detected and retried.

Hold Management

Withdrawals place holds immediately, preventing concurrent overdrafts.

Delta-Based Tracking

Changes tracked as deltas, not snapshots, preserving concurrent modifications.

Example Scenario

Time 10:00 - Balance: 10,000
Time 10:01 - Withdrawal 2,000 PENDING (hold placed)
Time 10:02 - Deposit 5,000 COMPLETED (balance: 13,000)
Time 10:03 - Withdrawal 2,000 COMPLETED (balance: 11,000)

Final: 11,000 ✓ (all transactions preserved)

---

Error Handling

All transactions use standard error codes:

Error Code	Description	Action
00	Success	Transaction completed
01	Insufficient funds	Check balance
05	Account locked	Contact operations
12	Invalid amount	Verify amount
51	Limit exceeded	Increase limit or split
91	System error	Retry or contact support

---

Best Practices

For Developers

1. Always use TransactionImpactRecord for tracking
2. Track every field change with delta
3. Use hold management for debits
4. Implement approval workflows
5. Test concurrent scenarios
6. Validate limits before execution

For Operators

1. Review pending transactions daily
2. Monitor limit breaches
3. Investigate unusual patterns
4. Verify till balances at EOD
5. Review reversal requests promptly
6. Maintain audit trail documentation

For Product Managers

1. Configure appropriate limits
2. Define clear approval thresholds
3. Set up narration templates
4. Configure fee structures
5. Monitor transaction volumes
6. Review and update policies

---

Next Steps

Explore specific transaction types:

• Deposit Transaction - Technical Flow →
• Withdrawal Transaction - Technical Flow →
• Transfer Transaction - Technical Flow →
• Initiate Deposit - Business Guide →
• Initiate Withdrawal - Business Guide →
• Initiate Transfer - Business Guide →

For implementation:

• See API Reference - Deposit Transactions
• See Product Configuration - Deposit Products
• See Accounting Configuration Guide

---

Last Updated: January 4, 2026
Version: 2.0
Status: Production Ready