Skip to main content

Teller Transactions API

Overview​

The Teller Transactions API provides endpoints for processing customer transactions at teller counters. These operations involve physical cash handling and direct customer interaction, distinguishing them from automated channel transactions (ATM, mobile banking, etc.).

What Are Teller Transactions?

Teller transactions are customer-facing operations where:

  • Physical cash is exchanged at the teller counter
  • The till balance is directly impacted by cash movements
  • Customer identity verification is required
  • Transactions are processed in real-time with immediate account updates
  • Audit trails capture teller, customer, and cash handling details

Core Transaction Types​

1. Teller Deposit​

Accept cash from customers and credit their deposit accounts.

Command: InitiateDepositCommand
Impact: Till balance ↑ | Account balance ↑
Cash Flow: Customer → Till → Account

Learn more →

2. Teller Withdrawal​

Pay out cash to customers and debit their deposit accounts.

Command: InitiateWithdrawalCommand
Impact: Till balance ↓ | Account balance ↓
Cash Flow: Account → Till → Customer

Learn more →

3. Teller Transfer​

Transfer funds between customer accounts without physical cash.

Command: InitiateTransferCommand
Impact: Till balance (no change) | Both accounts updated
Cash Flow: No cash involved - book transfer only

Learn more →

4. Loan Repayment with Teller​

Accept cash from customers to repay loan obligations.

Command: RecordLoanRepaymentCommand
Impact: Till balance ↑ | Loan balance ↓
Cash Flow: Customer → Till → Loan Account

Learn more →

5. Transaction Reversal​

Reverse incorrectly processed teller transactions.

Command: ReverseTellerTransactionCommand
Impact: Restores original state
Cash Flow: Reverses original transaction

Learn more →

Key Distinctions​

Till Operations vs. Teller Transactions

It's crucial to understand the difference:

AspectTeller TransactionsTill Operations
Customer Involvement✅ Yes - Customer present❌ No - Internal only
Cash Source/DestinationCustomerVault/Another Till
Account Impact✅ Customer account updated❌ No customer accounts
Till Balance Impact✅ Yes✅ Yes
ExamplesDeposit, WithdrawalAdd cash to till, Remove cash from till
DocumentationThis sectionTill Accounts →

Teller Transactions: Customer brings/receives cash → Account is credited/debited
Till Operations: Internal cash management → No customer accounts involved

BPMCore Architecture​

All teller transactions are processed through the BPMCore command engine:

Command Handlers​

CommandHandlerPurpose
InitiateDepositCommandAdministrationCoreDepositTransactionCommandHandlersProcess deposits
InitiateWithdrawalCommandAdministrationCoreDepositTransactionCommandHandlersProcess withdrawals
InitiateTransferCommandAdministrationCoreDepositTransactionCommandHandlersProcess transfers
RecordLoanRepaymentCommandAdministrationCoreLoanTransactionCommandHandlersProcess loan repayments
ReverseTellerTransactionCommandAdministrationCoreTransactionReversalHandlersReverse transactions

Transaction Flow​

Standard Teller Transaction Flow​

Transaction States​

All teller transactions follow this state machine:

Common Validations​

All teller transactions perform these validations:

1. Channel Validation​

  • Channel code must exist and be active
  • Channel must be configured for teller operations
  • Channel must support the requested transaction type
  • Channel GL accounts must be configured

2. Till Validation​

  • Till must be in OPENED state
  • Teller must be assigned to the till
  • Till must belong to the correct branch
  • For withdrawals: Till must have sufficient cash

3. Account Validation​

  • Account must exist in the system
  • Account must be ACTIVE (not Locked, Frozen, or Dormant)
  • Account must belong to a valid customer
  • Account type must support the transaction

4. Amount Validation​

  • Amount must be positive (> 0)
  • Amount must respect account tier limits
  • For withdrawals: Account must have sufficient balance
  • Precision must match currency configuration

5. Limit Validation​

  • Single transaction limits (account tier)
  • Daily transaction limits (account tier)
  • Monthly frequency limits (for savings accounts)
  • Account maximum balance (for deposits)

Response Structure​

All teller transaction commands return a consistent response structure:

Success Response​

{
  "isSuccessful": true,
  "message": "Transaction processed successfully",
  "statusCode": "00",
  "data": {
    "transactionId": "TXN-20250119-001234",
    "accountNumber": "101-001",
    "accountBalance": 15000.00,
    "transactionAmount": 5000.00,
    "tillBalance": 85000.00,
    "transactionDate": "2025-01-19T10:30:00Z",
    "reference": "REF-001234",
    "narration": "Transaction description",
    "transactionType": "Deposit"
  }
}

Error Response​

{
  "isSuccessful": false,
  "message": "Descriptive error message",
  "errorCode": "ERROR_CODE",
  "statusCode": "51",
  "data": {
    "accountNumber": "101-001",
    "requestedAmount": 5000.00,
    "availableBalance": 3000.00,
    "minimumBalance": 100.00
  }
}

Common Status Codes​

CodeMeaningTypical Scenarios
00SuccessTransaction completed
51Insufficient fundsWithdrawal/transfer exceeds balance
06ErrorAccount locked, frozen, or dormant
12Invalid transactionAccount type doesn't support operation
14Invalid accountAccount not found
30Format errorInvalid amount or parameters

GL Posting Patterns​

Deposit GL Entry​

Dr  Till GL Account               Amount
    Cr  Customer Account                     Amount

Withdrawal GL Entry​

Dr  Customer Account              Amount
    Cr  Till GL Account                      Amount

Transfer GL Entry​

Dr  Destination Account           Amount
    Cr  Source Account                       Amount

Note: Till is NOT involved in transfers (no cash movement).

Till Balance Management​

Critical Till Balance Monitoring

Tellers must actively manage till balances throughout the day:

Till balance increases with:

  • Customer deposits ✅
  • Cash added from vault ✅
  • Cash received from another till ✅

Till balance decreases with:

  • Customer withdrawals ✅
  • Cash removed to vault ✅
  • Cash transferred to another till ✅

Till balance NOT affected by:

  • Account-to-account transfers ❌
  • Channel transactions (ATM, mobile) ❌
  • GL corrections ❌

Till Capacity Planning​

ActionWhenDocumentation
Add cash to tillBefore opening, during busy periodAdd Cash →
Remove excess cashTill near capacityRemove Cash →
Transfer between tillsBalance workloadTransfer →
Vault depositEnd of day, excess cashVault Deposit →
Vault withdrawalTill running lowVault Withdrawal →

Security and Compliance​

Customer Identity Verification​

All teller transactions require customer identity verification:

Transaction AmountVerification Level
< $1,000Basic: ID + Signature
$1,000 - $5,000Enhanced: ID + Signature + Security Questions
$5,000 - $10,000Strong: ID + Signature + Biometrics + Manager Approval
> $10,000Maximum: All above + Source of Funds + Enhanced Due Diligence

Audit Trail​

Every teller transaction creates comprehensive audit records:

  • Transaction Details: Type, amount, currency, reference
  • Customer Information: ID, account number, name
  • Teller Information: User ID, till ID, branch
  • Timestamps: Request, processing, completion
  • Balances: Before/after for account and till
  • Approval: Supervisor approval (if required)
  • System: IP address, terminal ID, session
  • Cash: Denomination breakdown (if captured)

Fraud Prevention​

  • Real-time monitoring for suspicious patterns
  • Velocity limits (transaction frequency checks)
  • Amount threshold alerts
  • Dormant account activation alerts
  • Cross-reference with customer profile
  • Integration with fraud detection systems

Integration Points​

ModuleRelationshipUse Case
Till AccountsDirectTill management, cash operations
Deposit AccountsDirectAccount creation and management
Deposit TransactionsRelatedChannel transactions (non-teller)
Loan TransactionsRelatedLoan repayments
Vault TransactionsSupportingTill replenishment
Branch ManagementSupportingBranch configuration

Supporting Operations​

Best Practices​

For Developers​

  1. Always validate till state before processing transactions
  2. Use appropriate transaction type (CoreTransactionType enum)
  3. Handle errors gracefully with clear messages
  4. Log all transactions with complete context
  5. Respect channel configuration for GL posting
  6. Test edge cases: minimum balance, overdraft, limits
  7. Implement idempotency to prevent duplicate transactions

For Tellers​

  1. Verify customer identity before any transaction
  2. Count cash carefully in front of customer
  3. Check account status before accepting cash
  4. Monitor till balance throughout the day
  5. Provide receipts immediately after transaction
  6. Secure till when not in use
  7. Report suspicious activity to supervisor
  8. Balance till at end of day

Error Handling Guide​

Common Errors and Resolutions​

ErrorCauseResolution
TILL_NOT_OPENTill is closedOpen till
ACCOUNT_IS_RESTRICTEDAccount locked/frozen/dormantCheck account status, escalate to manager
INSUFFICIENT_FUNDSBalance too lowVerify with customer, suggest alternative
TILL_INSUFFICIENT_CASHTill has no cashWithdraw from vault
LIMIT_EXCEEDEDAmount exceeds tier limitSplit transaction or request limit increase
CHANNEL_NOT_FOUNDInvalid channel codeVerify channel configuration

Performance Considerations​

  • Real-time processing: All transactions execute in real-time
  • Average processing time: < 2 seconds per transaction
  • Concurrent transactions: System supports multiple tellers simultaneously
  • Peak hour handling: Scales to handle branch rush hours
  • Offline capability: Some terminals support offline mode with later sync

API Documentation Standards​

All endpoints in this module follow these conventions:

  • Command-based: Uses BPMCore command pattern
  • Consistent responses: Standard success/error structure
  • Validation-first: Comprehensive pre-transaction validation
  • Audit-complete: Full audit trail for all operations
  • Error-descriptive: Clear error messages for troubleshooting

Quick Navigation​

Core Operations:

Supporting Operations:

Till Management: