Initiate Deposit

Overview

The Initiate Deposit API allows financial institutions to process deposit transactions into customer deposit accounts. This operation credits the account balance, updates transaction history, and handles all necessary accounting entries through configurable channels (such as teller transactions, mobile banking, or ATMs).

Command Details

Command Name: InitiateDepositCommand

Operation Type: Command (Write Operation)

Transaction Type: Deposit

Use Cases

• Cash Deposits: Process over-the-counter cash deposits at bank branches
• Check Deposits: Record check deposits with appropriate hold periods
• Mobile/Online Deposits: Handle digital channel deposits (mobile banking, internet banking)
• ATM Deposits: Process automated teller machine deposit transactions
• Third-Party Deposits: Accept deposits made on behalf of account holders
• Bulk Deposits: Process multiple deposit transactions for payroll or batch operations

API Endpoint

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

Request Structure

Request Body

{
  "commandName": "InitiateDepositCommand",
  "data": {
    "accountEncodedKey": "string",
    "channelCode": "string",
    "amount": 0.00,
    "transactionType": 1,
    "notes": "string",
    "serviceId": "string",
    "serviceDescription": "string",
    "isBackDated": false,
    "backDateValueDate": "2025-12-17T10:30:00Z",
    "isBookingDate": false,
    "bookingDate": "2025-12-17T10:30:00Z",
    "entryDate": "2025-12-17T10:30:00Z"
  }
}

Request Fields

Field Name	Type	Mandatory	Description	Additional Information
accountEncodedKey	String	Yes	Unique identifier or account number of the deposit account	Can be either encodedKey or account number
channelCode	String	Yes	Code identifying the transaction channel	Must be a valid channel code (e.g., TELLER, MOBILE, ATM, BRANCH)
amount	Decimal	Yes	Deposit amount	Must be positive number with up to 2 decimal places
transactionType	Integer	Yes	Type of core transaction	Default: 1 (Deposit). Enum: CoreTransactionType
requireApproval	Boolean	No	Whether transaction requires approval before settlement	Default: false. When true, transaction enters PENDING state awaiting approval
notes	String	No	Transaction notes or remarks	Free text field for additional information
serviceId	String	No	Service identifier for the transaction	Used for tracking specific services
serviceDescription	String	No	Description of the service	Human-readable service description
isBackDated	Boolean	No	Whether transaction is backdated	Default: false. Requires backDateValueDate if true
backDateValueDate	DateTime	Conditional	Value date for backdated transaction	Required if isBackDated is true. ISO 8601 format
isBookingDate	Boolean	No	Whether to use specific booking date	Default: false. Requires bookingDate if true
bookingDate	DateTime	Conditional	Specific booking date for transaction	Required if isBookingDate is true. ISO 8601 format
entryDate	DateTime	No	Transaction entry date	ISO 8601 format. Defaults to current date/time

Approval Workflow

Overview

BankLingo deposit transactions support two execution modes controlled by the requireApproval parameter:

1. Direct Execution (SETTLED) - Transaction executes immediately and settles
2. Approval Required (PENDING) - Transaction awaits supervisory approval before settlement

This flexible workflow enables financial institutions to implement risk-based transaction controls, dual authorization requirements, and compliance policies while maintaining operational efficiency for routine transactions.

Transaction States

SETTLED State (Direct Execution)

When requireApproval is false or omitted (default behavior):

• ✅ Transaction executes immediately
• ✅ Account balance updated in real-time
• ✅ General Ledger (GL) entries posted
• ✅ Transaction fully completed - no approval needed
• ✅ Customer sees updated balance immediately

Balance Impact:

Account Balance = Old Balance + Deposit Amount
Available Balance = Account Balance - HoldAmount

Use Cases:

• Standard teller deposits within approved limits
• Automated channel deposits (ATM, mobile banking, online banking)
• Routine transactions below approval thresholds
• Bulk deposit processing for payroll
• Low-risk transactions

PENDING State (Approval Required)

When requireApproval is true:

• ⏳ Transaction enters PENDING state
• ⏳ Hold placed on account (HoldAmount increased)
• ⏳ Account balance remains UNCHANGED (awaiting approval)
• ⏳ GL entries NOT posted until approved
• ⏳ Transaction appears in pending approval queue
• ⏳ Customer does NOT see balance change yet

Balance Impact:

Account Balance = UNCHANGED (awaiting approval)
HoldAmount = Old HoldAmount + Deposit Amount
Available Balance = Account Balance - HoldAmount

Use Cases:

• High-value deposits exceeding approval thresholds
• Suspicious or unusual deposit patterns requiring review
• First-time large deposits from new customers
• Bulk import deposits requiring validation
• Deposits requiring dual authorization per compliance policy
• Risk-flagged transactions

State Transition Diagram

Universal Transaction Management Commands

BankLingo provides universal commands that work across all transaction types (deposits, withdrawals, loans, cheques, etc.) for managing transaction lifecycle. These commands use the TransactionImpactRecord system to intelligently track and reverse changes.

1. Approve Transaction (PENDING → SETTLED)

Command: ApproveTransactionCommand

Purpose: Approves a PENDING transaction and settles it, completing the deposit

Request:

{
  "commandName": "ApproveTransactionCommand",
  "data": {
    "transactionKey": "DEP123456",
    "approverNotes": "Verified customer identity and source of funds. Approved."
  }
}

Effect:

• ✅ Transaction state changes from PENDING → SETTLED
• ✅ Hold released (HoldAmount decreased by deposit amount)
• ✅ Account balance updated (increased by deposit amount)
• ✅ GL entries posted (debit cash/channel, credit customer deposits)
• ✅ Transaction completed and customer notified
• ✅ Approval audit trail recorded

Balance Impact:

Account Balance = Old Balance + Deposit Amount
HoldAmount = Old HoldAmount - Deposit Amount
Available Balance = Account Balance - HoldAmount

Authorization: Requires approver role/permissions

2. Reject Transaction (PENDING → CANCELLED)

Command: RejectTransactionCommand

Purpose: Rejects a PENDING transaction (internally uses CancelTransactionCommand)

Request:

{
  "commandName": "RejectTransactionCommand",
  "data": {
    "transactionKey": "DEP123456",
    "rejectionReason": "Insufficient documentation provided. Cannot verify source of funds."
  }
}

Effect:

• ❌ Transaction state changes from PENDING → CANCELLED
• ❌ Hold released (HoldAmount decreased)
• ❌ Account balance remains unchanged (deposit not applied)
• ❌ Transaction voided and removed from approval queue
• ❌ Customer notified of rejection
• ❌ Rejection audit trail recorded

Balance Impact:

Account Balance = UNCHANGED (deposit never applied)
HoldAmount = Old HoldAmount - Deposit Amount (hold released)
Available Balance = Account Balance - HoldAmount

Authorization: Requires approver role/permissions

Note: Rejection is permanent and cannot be undone. Customer must initiate new deposit transaction.

3. Cancel Transaction (PENDING → CANCELLED)

Command: CancelTransactionCommand

Purpose: Cancels a PENDING transaction before approval

Request:

{
  "commandName": "CancelTransactionCommand",
  "data": {
    "transactionKey": "DEP123456",
    "cancellationReason": "Customer request - duplicate transaction submitted"
  }
}

Effect:

• ❌ Same effect as Reject Transaction
• ❌ Transaction state changes from PENDING → CANCELLED
• ❌ Hold released, balance unchanged
• ❌ Transaction voided

Balance Impact:

Account Balance = UNCHANGED
HoldAmount = Old HoldAmount - Deposit Amount (hold released)

Authorization: Can be performed by transaction initiator or supervisor

Use Cases:

• Customer realizes deposit was entered incorrectly
• Duplicate transaction detected before approval
• Transaction no longer needed before approval

4. Reverse Transaction (SETTLED → REVERSED)

Command: ReverseTransactionCommand

Purpose: Reverses a SETTLED (completed) transaction, effectively undoing the deposit

Request:

{
  "commandName": "ReverseTransactionCommand",
  "data": {
    "transactionKey": "DEP123456",
    "reversalReason": "Deposit was applied to wrong account. Customer account: 9876543210 should have been credited instead."
  }
}

Effect:

• ⏪ Transaction state changes from SETTLED → REVERSED
• ⏪ Account balance decreased (reverses deposit)
• ⏪ Reverse GL entries posted (reverses original accounting)
• ⏪ Uses TransactionImpactRecord to intelligently reverse all changes
• ⏪ Original transaction preserved for audit (not deleted)
• ⏪ Reversal transaction created and linked to original
• ⏪ Customer notified of reversal

Balance Impact:

Account Balance = Old Balance - Deposit Amount (reversed)
Available Balance = Account Balance - HoldAmount

Authorization: Requires supervisor/admin role with reversal permissions

Important Notes:

• ⚠️ Reverse only works on SETTLED transactions
• ⚠️ PENDING transactions must be cancelled instead (cannot reverse what hasn't settled)
• ⚠️ Reversal creates audit trail maintaining original transaction
• ⚠️ If subsequent transactions occurred, system handles automatically using impact tracking

Use Cases:

• Deposit applied to wrong account
• Duplicate deposit needs to be reversed
• Customer requests reversal after settlement
• Error correction after transaction completed

Transaction Impact Tracking

All deposit transactions in BankLingo use the TransactionImpactRecord system to track changes comprehensively:

Key Features:

1. Entity Change Recording

   • Every field change is recorded: OldValue, NewValue, DeltaAmount
   • All affected entities tracked (account balance, GL accounts, fees, etc.)
   • Complete snapshot of what changed when

2. Intelligent Reversibility

   • Enables reversal without knowing specific transaction details
   • System automatically applies inverse deltas
   • Handles complex scenarios (fees, GL entries, balance changes)

3. Audit Trail

   • Complete history of all changes
   • Who, what, when, why for every transaction state change
   • Regulatory compliance and internal audit support

4. Universal Command Support

   • Approve, Reject, Cancel, Reverse commands work across ALL transaction types
   • Consistent behavior for deposits, withdrawals, loans, cheques, teller operations
   • Reduces code complexity and ensures reliability

Approval Workflow Best Practices

When to Use requireApproval = true

1. High-Value Transactions

• Deposits exceeding institutional risk thresholds
• Amount triggers configured per account tier or product
• Bulk deposit imports requiring validation
• Example: Deposits > $10,000 require supervisory approval

2. Risk Management

• Suspicious or unusual deposit patterns
• Deposits from high-risk customers or PEP (Politically Exposed Persons)
• First-time large deposits from new customers
• Deposits flagged by AML/KYC screening
• Cross-border deposits requiring compliance review

3. Compliance & Audit

• Transactions requiring dual authorization (maker-checker)
• Regulatory compliance requirements (BSA, AML, KYC)
• Internal control policies (Sarbanes-Oxley, Basel III)
• Cash deposits exceeding CTR (Currency Transaction Report) thresholds

4. Operational Controls

• Teller training period - all transactions require supervisor approval
• After-hours deposits requiring next-day approval
• Deposits during system maintenance or reconciliation periods

When to Use requireApproval = false (Direct Execution)

1. Standard Operations

• Regular teller deposits within approved limits
• Automated channel deposits (ATM, mobile, online banking)
• Low-value routine transactions below thresholds
• Customer self-service transactions

2. Performance & Efficiency

• High-volume transactions where approval adds no value
• Real-time balance updates required for customer experience
• Automated bulk processing (payroll deposits)

3. Customer Experience

• Immediate deposit confirmation needed
• Channel transactions requiring instant feedback
• Competitive advantage in digital banking

Configuration Recommendations

Approval Thresholds by Account Tier:

Account Tier	Approval Threshold	Rationale
Basic	> $5,000	Lower limit for basic accounts
Premium	> $25,000	Higher limit for verified customers
Corporate	> $100,000	Corporate accounts with established history
Trust/Fiduciary	All deposits	Regulatory requirement for trust accounts

Channel-Based Rules:

Channel	Direct Execution	Approval Required
Mobile Banking	≤ $5,000	> $5,000
ATM	≤ $2,000	> $2,000
Teller (Regular)	≤ $10,000	> $10,000
Teller (New Customer)	≤ $1,000	> $1,000
Bulk Import	Never	Always

Sample Requests

1. Standard Cash Deposit (Teller)

{
  "commandName": "InitiateDepositCommand",
  "data": {
    "accountEncodedKey": "8a8e87e87d1234567890abcd",
    "channelCode": "TELLER",
    "amount": 5000.00,
    "transactionType": 1,
    "notes": "Cash deposit - customer counter transaction"
  }
}

2. Mobile Banking Deposit with Service Tracking

{
  "commandName": "InitiateDepositCommand",
  "data": {
    "accountEncodedKey": "1234567890",
    "channelCode": "MOBILE",
    "amount": 1500.50,
    "transactionType": 1,
    "notes": "Mobile app deposit via bank transfer",
    "serviceId": "MOB-DEP-2025-001",
    "serviceDescription": "Mobile Banking Deposit Service"
  }
}

3. Backdated Deposit (Administrative Correction)

{
  "commandName": "InitiateDepositCommand",
  "data": {
    "accountEncodedKey": "8a8e87e87d1234567890abcd",
    "channelCode": "BRANCH",
    "amount": 25000.00,
    "transactionType": 1,
    "notes": "Correcting missed deposit from previous day",
    "isBackDated": true,
    "backDateValueDate": "2025-12-16T15:00:00Z"
  }
}

4. Check Deposit with Custom Booking Date

{
  "commandName": "InitiateDepositCommand",
  "data": {
    "accountEncodedKey": "1234567890",
    "channelCode": "TELLER",
    "amount": 10000.00,
    "transactionType": 1,
    "notes": "Check deposit - ABC Bank check #789456",
    "isBookingDate": true,
    "bookingDate": "2025-12-20T00:00:00Z"
  }
}

5. High-Value Deposit Requiring Approval (PENDING State)

{
  "commandName": "InitiateDepositCommand",
  "data": {
    "accountEncodedKey": "8a8e87e87d1234567890abcd",
    "channelCode": "TELLER",
    "amount": 75000.00,
    "transactionType": 1,
    "requireApproval": true,
    "notes": "Large cash deposit - requires supervisory approval per bank policy"
  }
}

Expected Behavior:

• ⏳ Transaction enters PENDING state
• ⏳ HoldAmount increased by $75,000
• ⏳ Account balance unchanged (awaiting approval)
• ⏳ Transaction appears in approval queue
• ⏳ Customer receives "Transaction pending approval" notification

6. Bulk Import Deposit Requiring Validation

{
  "commandName": "InitiateDepositCommand",
  "data": {
    "accountEncodedKey": "1234567890",
    "channelCode": "BULK_IMPORT",
    "amount": 2500.00,
    "transactionType": 1,
    "requireApproval": true,
    "notes": "Payroll deposit from bulk file import - batch #PAY-2025-001",
    "serviceId": "BULK-PAYROLL",
    "serviceDescription": "Bulk Payroll Processing Service"
  }
}

Expected Behavior:

• ⏳ Transaction enters PENDING state for bulk validation
• ⏳ Batch supervisor can review all transactions in batch
• ⏳ Approval can be done individually or in batch
• ⏳ Account balance updated only after approval

7. Suspicious Deposit Flagged for Review

{
  "commandName": "InitiateDepositCommand",
  "data": {
    "accountEncodedKey": "8a8e87e87d1234567890abcd",
    "channelCode": "TELLER",
    "amount": 9500.00,
    "transactionType": 1,
    "requireApproval": true,
    "notes": "Cash deposit - unusual pattern detected. Flagged for AML review. Customer: John Doe, First large deposit in 6 months."
  }
}

Expected Behavior:

• ⏳ Transaction enters PENDING state for compliance review
• ⏳ AML/Compliance officer reviews transaction
• ⏳ Additional documentation may be requested
• ⏳ Approved after AML clearance OR rejected if suspicious

Response Structure

Success Response

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Deposit account has been added successfully.",
  "data": {
    "transactionKey": "1000245",
    "accountNumber": "1234567890",
    "accountOfficerEncodedKey": "8a8e87e87d0987654321",
    "branchEncodedKey": "8a8e87e87d1111222233",
    "clientEncodedKey": "8a8e87e87d4444555566",
    "depositEncodedKey": "8a8e87e87d1234567890abcd"
  }
}

Response Fields

Field Name	Type	Description
transactionKey	String	Unique transaction reference number
accountNumber	String	Account number where deposit was made
accountOfficerEncodedKey	String	Encoded key of the account officer
branchEncodedKey	String	Encoded key of the branch
clientEncodedKey	String	Encoded key of the client/customer
depositEncodedKey	String	Encoded key of the deposit account

Error Responses

1. Invalid Account

{
  "isSuccessful": false,
  "statusCode": "CBS_404",
  "message": "Invalid deposit account encoded key"
}

2. Account Restricted

{
  "isSuccessful": false,
  "statusCode": "CBS_400",
  "message": "You cannot perform any transaction on this account. It is presently locked."
}

3. Deposit Limit Exceeded

{
  "isSuccessful": false,
  "statusCode": "CBS_425",
  "message": "The deposit limit on the account tier is 100000.00 NGN."
}

4. Maximum Balance Exceeded

{
  "isSuccessful": false,
  "statusCode": "CBS_426",
  "message": "The maximum balance allowed on the account is 500000.00 NGN."
}

5. Invalid Channel

{
  "isSuccessful": false,
  "statusCode": "CBS_404",
  "message": "Invalid transaction channel code"
}

Business Logic

Transaction Processing Flow

1. Account Validation

   • Verify account exists and is accessible
   • Check account status (not frozen, locked, or dormant)
   • Validate account type allows deposits

2. Channel Validation

   • Validate channel code exists and is active
   • Verify channel is configured for deposit operations
   • Check channel has associated GL account

3. Limit Validation

   • Check against account tier deposit transaction limit
   • Verify maximum balance won't be exceeded
   • Validate single transaction amount limits
   • Check daily transaction count limits

4. Date Processing

   • Apply backdating if specified (requires backDateValueDate)
   • Set booking date if specified
   • Default to current date/time if no special dates

5. Fee Calculation

   • Calculate applicable deposit fees based on product configuration
   • Apply fee trigger rules (OnDeposit)
   • Generate fee transactions if applicable

6. Narration Generation

   • Execute customer narration template with transaction context
   • Execute channel narration template
   • Generate transaction ID from template

7. Transaction Creation

   • Create CBS transaction record
   • Generate unique transaction key
   • Set transaction state (PENDING or SETTLED based on approval requirements)

8. Account Updates

   • If pending approval: Increase hold amount, create amount lock transaction
   • If immediate settlement: Credit account balance, create deposit transaction
   • Update account state to Active if currently inactive
   • Create settlement transaction for channel

9. Persistence

   • Save all transaction records
   • Update account balances
   • Commit changes to database

Special Handling

Fixed Deposit Accounts:

• Deposits not allowed after maturity date is set
• Returns error message for attempted deposits during maturity

Savings Plan Accounts:

• Deposits not allowed after maturity date has passed
• Checks maturity date against current date

Pending Transactions:

• Amount is held (increases holdAmount)
• Amount lock transaction created with CREDIT_LOCKED state
• Account balance not updated until approval

Settled Transactions:

• Account balance immediately credited
• Deposit transaction created with new balance
• Account state set to Active

Account Balance Impact

Immediate Settlement (No Approval Required)

Before Transaction:

• Account Balance: 10,000.00
• Available Balance: 10,000.00
• Hold Amount: 0.00

Deposit: 5,000.00

After Transaction:

• Account Balance: 15,000.00
• Available Balance: 15,000.00
• Hold Amount: 0.00

Pending Approval

Before Transaction:

• Account Balance: 10,000.00
• Available Balance: 10,000.00
• Hold Amount: 0.00

Deposit (Pending): 5,000.00

After Transaction:

• Account Balance: 10,000.00 (unchanged)
• Available Balance: 10,000.00
• Hold Amount: 5,000.00 (locked until approved)

Related Operations

• InitiateWithdrawal - Process withdrawal transactions
• InitiateTransfer - Transfer funds between accounts
• ApproveDepositTransaction - Approve pending deposits
• RetrieveDepositTransactionList - Query transaction history

Architecture Diagram

Security Considerations

• Authentication: Requires valid bearer token
• Authorization: User must have permission to process deposits on the account
• Audit Trail: All deposits are logged with user information, timestamps, and IP addresses
• Channel Security: Channel must be properly configured and validated
• Amount Validation: Prevents negative amounts and enforces limits

Performance Considerations

• Transaction Speed: Typically completes in 200-500ms
• Database Impact: Creates 2-4 transaction records per deposit
• Caching: Channel configuration is cached for improved performance
• Concurrent Transactions: Uses database locking to prevent race conditions
• Indexing: Account number and transaction key are indexed for fast lookups

Troubleshooting

Issue: Account Not Found Error

Symptom: CBS_404 error with message "Invalid deposit account encoded key"

Possible Causes:

1. Incorrect account encoded key or account number
2. Account has been closed or deleted
3. Account belongs to different tenant

Solution:

1. Verify account encoded key is correct
2. Use RetrieveDepositByIdQuery to confirm account exists
3. Check account status and state

Issue: Account Locked Error

Symptom: CBS_400 error stating account is locked, frozen, or dormant

Possible Causes:

1. Account has been manually locked by administrator
2. Account is dormant due to inactivity
3. Regulatory freeze on account

Solution:

1. Check account IsOnFreeze flag
2. Verify DepositState is not Locked or Dormant
3. Unlock account using UnLockDepositAccountCommand if authorized
4. Reactivate dormant account through proper channels

Issue: Deposit Limit Exceeded

Symptom: CBS_425 error about deposit transaction limit

Possible Causes:

1. Deposit amount exceeds account tier single transaction limit
2. Daily transaction count limit reached
3. Maximum balance would be exceeded

Solution:

1. Check account tier limits in product configuration
2. Split large deposits into multiple transactions if allowed
3. Request tier upgrade for customer if needed
4. Use administrative override if authorized

Issue: Invalid Channel Code

Symptom: CBS_404 error for channel code

Possible Causes:

1. Channel code doesn't exist in system
2. Channel is inactive or disabled
3. Channel not configured for deposit operations
4. Typo in channel code

Solution:

1. Verify channel code with LookUpTransactionChannelsQuery
2. Check channel is active and deposit operation is enabled
3. Ensure channel has associated GL account
4. Contact system administrator for channel configuration

Issue: Backdated Transaction Fails

Symptom: Error stating backdate value date is required

Possible Causes:

1. isBackDated is true but backDateValueDate not provided
2. Back date is in future
3. Back date is too far in past (outside allowed window)

Solution:

1. Provide backDateValueDate when isBackDated is true
2. Ensure backdate is in the past
3. Check date format is ISO 8601
4. Verify backdating is allowed by business rules

Monitoring and Alerts

Key Metrics to Track

• Total deposit volume (amount)
• Deposit transaction count
• Success rate percentage
• Average transaction processing time
• Failed transaction rate
• Deposits by channel
• Pending vs settled ratio

Recommended Alerts

• Failed deposits exceeding 5% threshold
• Unusually large deposit amounts (potential fraud)
• Deposits to dormant accounts
• High volume of deposits to single account
• Processing time exceeding 1 second
• Channel unavailability

Audit and Compliance

Audit Log Entries

Every deposit transaction creates audit records including:

• Transaction key and timestamp
• User who initiated transaction
• Account number and customer details
• Amount and currency
• Channel used
• Before and after account balances
• Notes and remarks
• IP address and device information
• Approval workflow (if applicable)

Compliance Requirements

• Anti-Money Laundering (AML): Large deposits may trigger AML checks
• Know Your Customer (KYC): Account must have valid KYC documentation
• Transaction Limits: Must comply with regulatory transaction limits
• Reporting: Deposits may need to be reported to financial authorities
• Record Retention: Transaction records retained per regulatory requirements (typically 7+ years)

Code Examples

C# Example

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

JavaScript/TypeScript Example

interface InitiateDepositRequest {
  commandName: string;
  data: {
    accountEncodedKey: string;
    channelCode: string;
    amount: number;
    transactionType: number;
    notes?: string;
    serviceId?: string;
    serviceDescription?: string;
    isBackDated?: boolean;
    backDateValueDate?: string;
  };
}

interface DepositResponse {
  isSuccessful: boolean;
  statusCode: string;
  message: string;
  data?: {
    transactionKey: string;
    accountNumber: string;
    accountOfficerEncodedKey: string;
    branchEncodedKey: string;
    clientEncodedKey: string;
    depositEncodedKey: string;
  };
}

async function initiateDeposit(
  accountEncodedKey: string,
  channelCode: string,
  amount: number,
  notes?: string
): Promise<DepositResponse> {
  const request: InitiateDepositRequest = {
    commandName: 'InitiateDepositCommand',
    data: {
      accountEncodedKey,
      channelCode,
      amount,
      transactionType: 1,
      notes,
    },
  };

  const response = await fetch('https://api.banklingo.com/api/bpm/cmd', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${YOUR_ACCESS_TOKEN}`,
    },
    body: JSON.stringify(request),
  });

  const result: DepositResponse = await response.json();
  return result;
}

// Usage
const result = await initiateDeposit(
  '8a8e87e87d1234567890abcd',
  'MOBILE',
  1500.50,
  'Mobile banking deposit'
);

if (result.isSuccessful) {
  console.log(`Deposit successful! Transaction: ${result.data?.transactionKey}`);
} else {
  console.error(`Deposit failed: ${result.message}`);
}

Python Example

import requests
import json
from typing import Optional, Dict, Any
from datetime import datetime

class DepositService:
    def __init__(self, base_url: str, access_token: str):
        self.base_url = base_url
        self.access_token = access_token
        self.headers = {
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {access_token}'
        }
    
    def initiate_deposit(
        self,
        account_encoded_key: str,
        channel_code: str,
        amount: float,
        notes: Optional[str] = None,
        service_id: Optional[str] = None,
        is_backdated: bool = False,
        backdate_value_date: Optional[datetime] = None
    ) -> Dict[str, Any]:
        """
        Initiate a deposit transaction to a deposit account.
        
        Args:
            account_encoded_key: Account identifier (encoded key or account number)
            channel_code: Transaction channel code (e.g., 'TELLER', 'MOBILE')
            amount: Deposit amount (must be positive)
            notes: Optional transaction notes
            service_id: Optional service identifier
            is_backdated: Whether transaction is backdated
            backdate_value_date: Value date for backdated transaction
            
        Returns:
            Dictionary containing response with transaction details
        """
        payload = {
            'commandName': 'InitiateDepositCommand',
            'data': {
                'accountEncodedKey': account_encoded_key,
                'channelCode': channel_code,
                'amount': amount,
                'transactionType': 1,
            }
        }
        
        # Add optional fields
        if notes:
            payload['data']['notes'] = notes
        if service_id:
            payload['data']['serviceId'] = service_id
        if is_backdated:
            payload['data']['isBackDated'] = True
            if backdate_value_date:
                payload['data']['backDateValueDate'] = backdate_value_date.isoformat()
        
        response = requests.post(
            f'{self.base_url}/api/bpm/cmd',
            json=payload,
            headers=self.headers
        )
        
        return response.json()

# Usage
deposit_service = DepositService(
    base_url='https://api.banklingo.com',
    access_token='your-access-token-here'
)

result = deposit_service.initiate_deposit(
    account_encoded_key='8a8e87e87d1234567890abcd',
    channel_code='TELLER',
    amount=5000.00,
    notes='Cash deposit - counter transaction'
)

if result['isSuccessful']:
    print(f"Deposit successful!")
    print(f"Transaction Key: {result['data']['transactionKey']}")
    print(f"Account Number: {result['data']['accountNumber']}")
else:
    print(f"Deposit failed: {result['message']}")
    print(f"Status Code: {result['statusCode']}")

Response Codes

Code	Description	Resolution
00	Success	Deposit processed successfully
CBS_400	Bad Request / Account Locked	Check account status, ensure account is not frozen or locked
CBS_404	Account or Channel Not Found	Verify account encoded key and channel code
CBS_425	Deposit Limit Exceeded	Check account tier limits, split transaction, or request tier upgrade
CBS_426	Maximum Balance Exceeded	Verify maximum balance limit for account tier
CBS_427	Invalid Amount	Ensure amount is positive and properly formatted
CBS_428	Account Type Restriction	Check if account type allows deposits (e.g., fixed deposit during maturity)

Business Rules

Validation Rules

1. Account Encoded Key - Must correspond to an existing, active deposit account; can be either the encoded key or account number
2. Channel Code - Must be a valid, active transaction channel configured for deposit operations with associated GL account
3. Amount - Must be a positive decimal value with up to 2 decimal places; zero or negative amounts are rejected
4. Transaction Type - Must be valid CoreTransactionType enum value; defaults to 1 (Deposit)
5. Backdated Transactions - If isBackDated is true, backDateValueDate must be provided and must be in the past
6. Booking Date - If isBookingDate is true, bookingDate must be provided
7. Account Status - Account must not be frozen (IsOnFreeze = false), locked, or dormant
8. Account Type Restrictions - Fixed deposit accounts cannot accept deposits after maturity date is set; Savings plan accounts cannot accept deposits after maturity date has passed

Operational Rules

1. Deposits update account balance immediately for settled transactions, or create hold amount for pending transactions requiring approval
2. Transaction limits are enforced based on account tier configuration (single transaction limit, daily count limit, maximum balance)
3. Fees are calculated automatically based on product configuration and applied according to fee trigger rules (OnDeposit)
4. Narrations are generated from configurable templates using transaction context (account, channel, amount, etc.)
5. All deposit transactions create corresponding accounting entries: credit to customer account, debit to channel/GL account
6. Account state is automatically set to Active upon first successful deposit if previously inactive
7. Pending transactions (requiring approval) create amount lock transactions with CREDIT_LOCKED state until approved or rejected
8. Transaction keys are generated using configurable templates and sequence numbers to ensure uniqueness
9. Date handling supports backdating (for corrections) and custom booking dates (for future-dated transactions) with proper validation
10. All deposits are recorded in audit trail with complete transaction context including user, timestamp, IP address, and device information

Changelog

Version 1.0.0 - December 17, 2025

• Initial documentation
• Comprehensive field documentation with business rules
• Multiple code examples (C#, JavaScript, Python)
• Detailed business logic and transaction flow
• Troubleshooting guide with common scenarios
• Complete API specification with sample requests/responses

---

Last Updated: December 17, 2025

API Version: 1.0

Document Version: 1.0.0

---

Product Documentation

For business process and technical flow details, see:

• Deposit Transaction - Technical Flow
• Deposit Transactions Overview