Lock Deposit Account

Lock a deposit account to prevent all transactions (deposits, withdrawals, transfers) while maintaining the account structure and balance.

Overview

The LockDepositAccountCommand enables administrators to lock a deposit account, effectively freezing all transaction activity on the account. This is typically used for security purposes, regulatory compliance, legal holds, fraud prevention, or account investigations. Unlike amount locks which restrict specific funds, account locks prevent any transaction activity whatsoever.

Key Capabilities

• Complete Account Freeze: Prevents all deposits, withdrawals, and transfers
• State Management: Tracks previous account state for restoration
• Audit Trail: Records lock reason and user who initiated the lock
• Notification System: Triggers activity notifications for compliance
• Reversible: Can be unlocked using UnlockDepositAccountCommand
• Balance Preservation: Account balance remains intact during lock period

---

API Endpoint

POST /api/bpm/cmd

Headers

Content-Type: application/json
Authorization: Bearer {access_token}
X-Tenant-ID: {tenant_id}

---

Request Structure

Command Payload

{
  "commandName": "LockDepositAccountCommand",
  "data": {
    "accountEncodedKey": "string",
    "lockReason": "string"
  }
}

Request Fields

Field	Type	Required	Description	Validation
accountEncodedKey	string	Yes	Account number or encoded key to lock	Must exist in system
lockReason	string	Yes	Reason for locking the account	Mandatory for audit purposes

---

Response Structure

Success Response

{
  "isSuccessful": true,
  "message": "The deposit account has been locked successfully.",
  "statusCode": "00"
}

Error Response

{
  "isSuccessful": false,
  "message": "The deposit account has already been locked.",
  "statusCode": "INVALID_REQUEST"
}

Response Fields

Field	Type	Description
isSuccessful	boolean	Indicates if lock operation was successful
message	string	Descriptive result message
statusCode	string	Response code (00 = success)

---

Sample Requests

1. Lock Account for Fraud Investigation

{
  "commandName": "LockDepositAccountCommand",
  "data": {
    "accountEncodedKey": "ACC001234567",
    "lockReason": "Suspected fraudulent activity - Under investigation by compliance team"
  }
}

Use Case: Immediate account freeze when fraud is detected.

2. Lock Account for Legal Hold

{
  "commandName": "LockDepositAccountCommand",
  "data": {
    "accountEncodedKey": "8A3F2D1E9B5C4F7A6E8D2C1B3A9F5E7D",
    "lockReason": "Court order #CO-2024-5678 - Legal hold pending litigation"
  }
}

Use Case: Compliance with legal requirements for account freeze.

3. Lock Account for KYC Review

{
  "commandName": "LockDepositAccountCommand",
  "data": {
    "accountEncodedKey": "SAV987654321",
    "lockReason": "KYC documentation expired - Account locked pending document update"
  }
}

Use Case: Regulatory compliance when customer documentation needs renewal.

---

Business Logic

Processing Workflow

Validation Steps

1. Extract Request Fields: Get accountEncodedKey and lockReason from request data
2. Account Lookup: Query DepositAccount by account number or encoded key with related entities (Client, DepositProduct)
3. Account Existence Check: Verify account exists, return error if null
4. Duplicate Lock Check: Verify account is not already in Locked state
5. State Preservation: Store current account state in PreviousState field
6. State Update: Set DepositState to Locked
7. Database Update: Persist account changes
8. Activity Notification: Publish notification with lock reason for audit trail
9. Success Response: Return confirmation message

State Management

Before Lock:

Account State: Active | Approved | Dormant
PreviousState: [varies]
IsOnFreeze: false

After Lock:

Account State: Locked
PreviousState: [stores original state for restoration]
IsOnFreeze: remains unchanged

---

Error Responses

Common Errors

Error Code	Message	Scenario	Resolution
Client_Not_Found	"The deposit account does not exist."	Account number/key is invalid	Verify account identifier is correct
INVALID_REQUEST	"The deposit account has already been locked."	Account is already in Locked state	Use GetAccountDetails to check current state

---

Business Logic Details

Impact of Account Lock

When an account is locked:

1. All Deposits Blocked: No funds can be credited to the account
2. All Withdrawals Blocked: No funds can be debited from the account
3. All Transfers Blocked: Account cannot be source or destination for transfers
4. Balance Frozen: Current balance remains unchanged but is inaccessible
5. Interest Accrual: Continues based on product configuration (typically unaffected)
6. Fees and Charges: May continue to accrue depending on bank policy
7. Standing Orders: Blocked from executing
8. Card Transactions: Debit/ATM cards linked to account will be declined
9. Online Banking: Account visible but transactions disabled

Duration and Removal

• No Expiry: Locks remain until explicitly removed via UnlockDepositAccountCommand
• Permanent Lock: Can be maintained indefinitely for legal/compliance reasons
• Unlock Process: Requires appropriate authorization level
• State Restoration: Previous state is restored when unlocked

---

Security Considerations

Authorization

• Role-Based Access: Only users with appropriate permissions can lock accounts
• Supervisor Approval: May require additional approval based on bank policy
• Audit Logging: All lock operations logged with user, timestamp, and reason
• Compliance: Lock reasons should reference specific policy violations or legal orders

Data Protection

• Reason Visibility: Lock reasons visible in audit logs and activity feeds
• Customer Notification: Consider notifying customer of account lock (per bank policy)
• Balance Privacy: Balance information remains protected during lock period

---

Performance Considerations

Optimization

• Eager Loading: Loads Client and DepositProduct in single query to avoid N+1 issues
• Direct State Update: Simple state change without complex calculations
• Immediate Effect: Account locked instantly upon command execution
• Notification Async: Activity notifications published asynchronously

Expected Performance

• Lock Operation: < 200ms under normal load
• Database Impact: Single UPDATE statement
• No Complex Queries: No transaction history analysis required

---

Monitoring & Alerts

Key Metrics

• Daily Lock Count: Track number of accounts locked per day
• Lock Reasons Distribution: Categorize locks by reason (fraud, legal, KYC, etc.)
• Lock Duration: Monitor how long accounts remain locked
• Unlock Rate: Percentage of locked accounts that get unlocked
• User Activity: Track which users perform most lock operations

Alert Thresholds

• High Lock Volume: > 50 accounts locked in 1 hour (potential system issue)
• Long Lock Duration: Account locked > 90 days (review required)
• Repeated Locks: Same account locked/unlocked > 3 times in 24 hours

---

Audit & Compliance

Audit Trail

Every account lock records:

• User Context: Username and UserEncodedKey who initiated lock
• Timestamp: Exact date and time of lock
• Account Details: Account number, client name, product name
• Lock Reason: Full text of reason provided
• Previous State: Account state before lock
• Activity Type: LockDepositAccount action logged

Compliance Requirements

• Regulatory Reporting: Locked accounts must be reported to regulators
• Customer Rights: Customers have right to know reason for account lock
• Documentation: Lock reason must reference specific policy or legal document
• Review Period: Locked accounts should be reviewed periodically
• Unlock Authorization: Clear process for removing locks

---

Code Examples

C# Implementation

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

public class BankLingoAccountLockClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;

    public BankLingoAccountLockClient(string baseUrl, string accessToken, string tenantId)
    {
        _baseUrl = baseUrl;
        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Authorization = 
            new AuthenticationHeaderValue("Bearer", accessToken);
        _httpClient.DefaultRequestHeaders.Add("X-Tenant-ID", tenantId);
    }

    public async Task<LockAccountResponse> LockDepositAccountAsync(
        string accountEncodedKey,
        string lockReason)
    {
        var request = new
        {
            commandName = "LockDepositAccountCommand",
            data = new
            {
                accountEncodedKey,
                lockReason
            }
        };

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

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

        var responseJson = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize<LockAccountResponse>(responseJson);
    }
}

public class LockAccountResponse
{
    public bool IsSuccessful { get; set; }
    public string Message { get; set; }
    public string StatusCode { get; set; }
}

// Usage
var client = new BankLingoAccountLockClient(
    "https://api.banklingo.com",
    "your-jwt-token",
    "your-tenant-id"
);

var result = await client.LockDepositAccountAsync(
    accountEncodedKey: "ACC001234567",
    lockReason: "Suspected fraudulent activity - Under investigation"
);

if (result.IsSuccessful)
{
    Console.WriteLine("Account locked successfully!");
}
else
{
    Console.WriteLine($"Lock failed: {result.Message}");
}

JavaScript Implementation

class BankLingoAccountLockClient {
    constructor(baseUrl, accessToken, tenantId) {
        this.baseUrl = baseUrl;
        this.accessToken = accessToken;
        this.tenantId = tenantId;
    }

    async lockDepositAccount(accountEncodedKey, lockReason) {
        const request = {
            commandName: 'LockDepositAccountCommand',
            data: {
                accountEncodedKey,
                lockReason
            }
        };

        const response = await fetch(`${this.baseUrl}/api/bpm/cmd`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${this.accessToken}`,
                'X-Tenant-ID': this.tenantId
            },
            body: JSON.stringify(request)
        });

        return await response.json();
    }
}

// Usage
const client = new BankLingoAccountLockClient(
    'https://api.banklingo.com',
    'your-jwt-token',
    'your-tenant-id'
);

const result = await client.lockDepositAccount(
    'ACC001234567',
    'Suspected fraudulent activity - Under investigation'
);

if (result.isSuccessful) {
    console.log('Account locked successfully!');
} else {
    console.error(`Lock failed: ${result.message}`);
}

Python Implementation

import requests
from typing import Optional
from dataclasses import dataclass

@dataclass
class LockAccountResponse:
    is_successful: bool
    message: str
    status_code: str

class BankLingoAccountLockClient:
    def __init__(self, base_url: str, access_token: str, tenant_id: str):
        self.base_url = base_url
        self.headers = {
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {access_token}',
            'X-Tenant-ID': tenant_id
        }

    def lock_deposit_account(
        self,
        account_encoded_key: str,
        lock_reason: str
    ) -> LockAccountResponse:
        request_data = {
            'commandName': 'LockDepositAccountCommand',
            'data': {
                'accountEncodedKey': account_encoded_key,
                'lockReason': lock_reason
            }
        }

        response = requests.post(
            f'{self.base_url}/api/bpm/cmd',
            headers=self.headers,
            json=request_data
        )

        result = response.json()
        return LockAccountResponse(
            is_successful=result.get('isSuccessful', False),
            message=result.get('message', ''),
            status_code=result.get('statusCode', '')
        )

# Usage
client = BankLingoAccountLockClient(
    base_url='https://api.banklingo.com',
    access_token='your-jwt-token',
    tenant_id='your-tenant-id'
)

result = client.lock_deposit_account(
    account_encoded_key='ACC001234567',
    lock_reason='Suspected fraudulent activity - Under investigation'
)

if result.is_successful:
    print('Account locked successfully!')
else:
    print(f'Lock failed: {result.message}')

---

Response Codes

Code	Description	Action Required
00	Success - Account locked	No action needed
Client_Not_Found	Account does not exist	Verify account number/key
INVALID_REQUEST	Account already locked	Check account state first

---

Business Rules

Validation Rules

1. Account Required: accountEncodedKey must be provided and valid
2. Lock Reason Required: lockReason is mandatory for compliance
3. Account Existence: Account must exist in the system
4. No Duplicate Locks: Cannot lock an already locked account
5. Valid Identifier: Account can be identified by account number or encoded key

Operational Rules

1. State Preservation: Previous account state stored before applying lock
2. Immediate Effect: Lock takes effect immediately upon successful execution
3. Transaction Block: All transaction types (deposit, withdrawal, transfer) are blocked
4. Balance Unchanged: Account balance remains as-is during lock period
5. Unlock Capability: Locked accounts can be unlocked using UnlockDepositAccountCommand
6. Activity Logging: Lock operation logged with ActivityAction.LockDepositAccount
7. Notification Sent: Activity notification published for audit trail
8. User Context Recorded: User who initiated lock is recorded
9. No Automatic Expiry: Locks remain until explicitly removed
10. Related Entities Loaded: Client and DepositProduct loaded for notification context

---

Related Operations

• UnlockDepositAccountCommand: Remove lock and restore account to previous state
• ActivatePNDOnAccountCommand: Alternative restriction that only blocks debits
• LockDepositAmountCommand: Lock specific amount rather than entire account
• GetAccountDetailsQuery: Check current account state before locking

---

Troubleshooting

Issue: "Account already locked" Error

Symptom: Receive INVALID_REQUEST error when trying to lock account

Solution:

1. Query account details to verify current state
2. If already locked, use UnlockDepositAccountCommand first if needed
3. If state is correct but error persists, check database for state consistency

Issue: Unable to Perform Transactions After Lock

Symptom: All transactions on account are declined

Solution: This is expected behavior. Locked accounts cannot process any transactions. Use UnlockDepositAccountCommand to restore account access.

---

Changelog

Version	Date	Changes
1.0.0	2024-01-15	Initial implementation with state management
1.1.0	2024-03-20	Added activity notification for audit trail
1.2.0	2024-06-10	Enhanced error messages and validation

---

Support

For technical assistance with the LockDepositAccountCommand:

• Documentation: https://docs.banklingo.com/api/deposit-transactions/lock-deposit-account
• API Support: api-support@banklingo.com
• Developer Forum: https://community.banklingo.com/api-questions