Universal Transaction Management - Developer Reference

Overview

The Universal Transaction Management system provides a unified API for managing the lifecycle of all transactions across the BankLingo Core Banking System. These commands work consistently across:

• ✅ Deposit transactions (deposits, withdrawals, transfers)
• ✅ Loan transactions (disbursements, repayments, writeoffs)
• ✅ Teller transactions (over-the-counter operations)
• ✅ Till operations (cash management, till-to-till, till-to-vault)
• ✅ Vault operations (funding, transfers)
• ✅ Cheque transactions (deposits, withdrawals, clearing, bouncing)

Key Features

🎯 Transaction-Type Agnostic

All commands work using the CBSTransaction unified transaction table and TransactionImpactRecord tracking system. You don't need to know the specific transaction type - the system handles it automatically.

🔄 Complete Lifecycle Management

📊 Impact-Based Reversals

The system uses TransactionImpactRecord to track all entity changes. When reversing a transaction:

• Balance changes are automatically restored
• State transitions are reversed (e.g., ACTIVE → PENDING_APPROVAL)
• Hold amounts are released or re-applied
• Accounting entries are automatically journaled

---

Available Commands

1. Query Commands

Command	Purpose	Key Features
Get All Transactions	System-wide transaction search	Filtering, pagination, account lookups
Get Transaction Details	Single transaction with full history	Impact records, related entities, audit trail

2. Approval Workflow Commands

Command	Purpose	Transition
Approve Transaction	Approve pending transaction	PENDING → SETTLED
Reject Transaction	Reject transaction in workflow	PENDING → CANCELLED

3. Cancellation & Reversal Commands

Command	Purpose	Transition
Cancel Transaction	Cancel pending transaction	PENDING → CANCELLED
Reverse Transaction	Reverse completed transaction	SETTLED → REVERSED

---

Transaction States

State Definitions

State	Description	Balance Impact	Hold Impact	Reversible
PENDING	Awaiting approval	None	Increased	Yes (Cancel/Reject)
SETTLED	Completed successfully	Applied	Released	Yes (Reverse)
CANCELLED	Rejected before settlement	None	Released	No (Terminal)
REVERSED	Reversed after settlement	Restored	N/A	No (Terminal)

State Transitions

Creating a Transaction

// With approval required
POST /api/bpm/cmd/CreateDeposit
{
  "accountId": "...",
  "amount": 10000,
  "requireApproval": true  // → PENDING state
}

// Direct settlement (no approval)
POST /api/bpm/cmd/CreateDeposit
{
  "accountId": "...",
  "amount": 10000,
  "requireApproval": false  // → SETTLED state
}

Approval Path (PENDING → SETTLED)

// Approve transaction
POST /api/bpm/cmd/ApproveTransaction
{
  "transactionKey": "TRX-2026-001234",
  "approverNotes": "Verified customer identity"
}
// Result: PENDING → SETTLED, balance updated

Rejection Path (PENDING → CANCELLED)

// Option 1: Reject with workflow categorization
POST /api/bpm/cmd/RejectTransaction
{
  "transactionKey": "TRX-2026-001234",
  "rejectionReason": "Customer documents expired",
  "rejectionCategory": "INSUFFICIENT_DOCUMENTATION"
}

// Option 2: Simple cancellation
POST /api/bpm/cmd/CancelTransaction
{
  "transactionKey": "TRX-2026-001234",
  "reason": "Customer request"
}
// Result: PENDING → CANCELLED, holds released

Reversal Path (SETTLED → REVERSED)

// Reverse completed transaction
POST /api/bpm/cmd/ReverseTransaction
{
  "transactionKey": "TRX-2026-001234",
  "reversalReason": "Duplicate transaction detected",
  "reversalCategory": "DUPLICATE"
}
// Result: SETTLED → REVERSED, balance restored

---

Common Use Cases

Use Case 1: High-Value Deposit with Approval

Use Case 2: Suspicious Transaction Rejection

Use Case 3: Accidental Double-Payment Reversal

---

TransactionImpactRecord System

How It Works

Every transaction creates a TransactionImpactRecord that tracks all entity changes:

{
  "transactionId": "a1b2c3d4...",
  "impactedEntities": [
    {
      "entityType": "DepositAccount",
      "entityId": "account-123",
      "fieldName": "Balance",
      "oldValue": "50000.00",
      "newValue": "60000.00",
      "deltaAmount": "+10000.00"
    },
    {
      "entityType": "DepositAccount",
      "entityId": "account-123",
      "fieldName": "HoldAmount",
      "oldValue": "5000.00",
      "newValue": "0.00",
      "deltaAmount": "-5000.00"
    }
  ]
}

Benefits

✅ Automatic Reversal: System knows exactly what to undo
✅ Audit Trail: Complete history of all changes
✅ Type Safety: Works across all transaction types
✅ Rollback Support: Can reverse any settled transaction

---

Error Handling

Common Response Codes

Code	Meaning	Action
TRX_NOT_FOUND	Transaction doesn't exist	Verify transaction key
INVALID_STATE_TRANSITION	Cannot perform action in current state	Check transaction state
ALREADY_SETTLED	Cannot cancel settled transaction	Use ReverseTransaction instead
ALREADY_REVERSED	Transaction already reversed	Transaction is terminal
INSUFFICIENT_PERMISSIONS	User lacks approval rights	Check user roles

Example Error Response

{
  "success": false,
  "message": "Cannot cancel transaction in SETTLED state",
  "code": "INVALID_STATE_TRANSITION",
  "data": {
    "transactionKey": "TRX-2026-001234",
    "currentState": "SETTLED",
    "attemptedAction": "CANCEL",
    "suggestion": "Use ReverseTransaction to undo a settled transaction"
  }
}

---

Authentication & Authorization

Required Permissions

Operation	Required Role	Notes
Get All Transactions	ViewTransactions	Branch-level filtering applies
Get Transaction Details	ViewTransactions	Can only view own branch
Approve Transaction	ApproveTransactions	May require manager role
Reject Transaction	ApproveTransactions	Rejection reasons logged
Cancel Transaction	ManageTransactions	Can cancel own transactions
Reverse Transaction	ReverseTransactions	Typically manager-only

Branch-Level Security

All queries automatically filter by user's branch access:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

---

Best Practices

✅ DO

• ✅ Always provide descriptive reasons for cancellations/reversals
• ✅ Use appropriate rejection/reversal categories for reporting
• ✅ Check transaction state before attempting operations
• ✅ Include approver notes for audit trail
• ✅ Use pagination for large transaction queries

❌ DON'T

• ❌ Don't try to cancel SETTLED transactions (use reverse instead)
• ❌ Don't reverse PENDING transactions (use cancel instead)
• ❌ Don't skip approval workflow for high-value transactions
• ❌ Don't reuse transaction keys
• ❌ Don't query all transactions without filters

---

Next Steps

Choose a command to learn more:

• Get All Transactions - Query and search transactions
• Get Transaction Details - View full transaction history
• Approve Transaction - Approve pending transactions
• Reject Transaction - Reject transactions with categorization
• Cancel Transaction - Cancel pending transactions
• Reverse Transaction - Reverse settled transactions

---

Related Documentation

• Transaction Processing Overview
• Deposit Transactions
• Loan Transactions
• Teller Transactions
• Approval Workflows