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

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

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

using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class DepositService
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;
    private readonly string _bearerToken;

    public DepositService(HttpClient httpClient, string baseUrl, string bearerToken)
    {
        _httpClient = httpClient;
        _baseUrl = baseUrl;
        _bearerToken = bearerToken;
    }

    public async Task<DepositResponse> InitiateDepositAsync(string accountEncodedKey, 
        string channelCode, decimal amount, string notes = null)
    {
        var request = new
        {
            commandName = "InitiateDepositCommand",
            data = new
            {
                accountEncodedKey,
                channelCode,
                amount,
                transactionType = 1,
                notes
            }
        };

        var json = JsonSerializer.Serialize(request);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        _httpClient.DefaultRequestHeaders.Authorization = 
            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", _bearerToken);

        var response = await _httpClient.PostAsync($"{_baseUrl}/api/bpm/cmd", content);
        var responseJson = await response.Content.ReadAsStringAsync();

        return JsonSerializer.Deserialize<DepositResponse>(responseJson);
    }
}

public class DepositResponse
{
    public bool IsSuccessful { get; set; }
    public string StatusCode { get; set; }
    public string Message { get; set; }
    public DepositData Data { get; set; }
}

public class DepositData
{
    public string TransactionKey { get; set; }
    public string AccountNumber { get; set; }
    public string AccountOfficerEncodedKey { get; set; }
    public string BranchEncodedKey { get; set; }
    public string ClientEncodedKey { get; set; }
    public string DepositEncodedKey { get; set; }
}

// Usage
var depositService = new DepositService(httpClient, "https://api.banklingo.com", "your-token-here");
var result = await depositService.InitiateDepositAsync(
    "8a8e87e87d1234567890abcd",
    "TELLER",
    5000.00m,
    "Cash deposit at branch"
);

if (result.IsSuccessful)
{
    Console.WriteLine($"Deposit successful. Transaction Key: {result.Data.TransactionKey}");
}
else
{
    Console.WriteLine($"Deposit failed: {result.Message}");
}

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