Lock Deposit Amount

Overview

The Lock Deposit Amount API enables financial institutions to place a hold on a specific amount in a customer's deposit account. This operation reduces the available balance while maintaining the actual account balance, preventing the locked funds from being used in other transactions.

Command Details

Command Name: LockDepositAmountCommand

Operation Type: Command (Write Operation)

Transaction Type: AmountLock

Use Cases

• Card Authorization Holds: Lock funds for card transactions pending settlement
• Check Holds: Place holds on deposited checks pending clearance
• Regulatory Compliance: Lock funds for legal or regulatory requirements
• Collateral Management: Hold funds as collateral for loans or guarantees
• Payment Guarantees: Ensure funds availability for scheduled payments

API Endpoint

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

Request Structure

Request Body

{
  "commandName": "LockDepositAmountCommand",
  "data": {
    "accountEncodedKey": "string",
    "blockReference": "string",
    "amount": 0.00,
    "allowNegativeBalance": false,
    "lockReason": "string"
  }
}

Request Fields

Field Name	Type	Mandatory	Description	Additional Information
accountEncodedKey	String	Yes	The unique identifier or account number of the deposit account	Can be either the encoded key or account number
blockReference	String	Yes	Unique reference for this lock operation	Must be unique for the account. Used to identify and release/seize the lock
amount	Decimal	Yes	Amount to be locked	Must be a positive number. Precision up to 2 decimal places
allowNegativeBalance	Boolean	No	Whether to allow locking even if it results in negative balance	Default: false. Set to true for overdraft scenarios
lockReason	String	No	Description or reason for locking the amount	Free text field for audit trail purposes

Sample Requests

Example 1: Standard Amount Lock

{
  "commandName": "LockDepositAmountCommand",
  "data": {
    "accountEncodedKey": "8a818e8c7f2d7e39017f2d8f4b250001",
    "blockReference": "HOLD-2024-12-17-0001",
    "amount": 50000.00,
    "allowNegativeBalance": false,
    "lockReason": "Card authorization hold for POS transaction"
  }
}

Example 2: Check Hold

{
  "commandName": "LockDepositAmountCommand",
  "data": {
    "accountEncodedKey": "2000123456",
    "blockReference": "CHK-HOLD-202412170001",
    "amount": 150000.00,
    "lockReason": "Check hold - pending clearance for Check #12345"
  }
}

Example 3: Legal Hold

{
  "commandName": "LockDepositAmountCommand",
  "data": {
    "accountEncodedKey": "8a818e8c7f2d7e39017f2d8f4b250002",
    "blockReference": "LEGAL-HOLD-CT-2024-789",
    "amount": 2500000.00,
    "allowNegativeBalance": false,
    "lockReason": "Court order - Case #CT/2024/789"
  }
}

Example 4: Overdraft Scenario

{
  "commandName": "LockDepositAmountCommand",
  "data": {
    "accountEncodedKey": "8a818e8c7f2d7e39017f2d8f4b250003",
    "blockReference": "OD-LOCK-20241217-001",
    "amount": 75000.00,
    "allowNegativeBalance": true,
    "lockReason": "Overdraft facility lock"
  }
}

Response Structure

Success Response

HTTP Status: 200 OK

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Amount locked successfully.",
  "data": {
    "blockReference": "HOLD-2024-12-17-0001",
    "transactionId": "A7B3F2E1D9C8B6A5E4F3D2C1B0A98765"
  },
  "pages": 0,
  "hasNext": false,
  "hasPrevious": false,
  "count": 0,
  "size": 0
}

Success Response Fields

Field Name	Type	Description
isSuccessful	Boolean	Indicates operation success (true for successful locks)
statusCode	String	Response code ("00" for success)
message	String	Human-readable success message
data.blockReference	String	Echo of the block reference from request
data.transactionId	String	Unique transaction identifier for the lock operation

Error Response Examples

Error 1: Account Not Found

HTTP Status: 200 OK (Application-level error)

{
  "isSuccessful": false,
  "statusCode": "CBS_404",
  "message": "The account number is not valid",
  "data": null
}

Error 2: Duplicate Block Reference

{
  "isSuccessful": false,
  "statusCode": "CBS_409",
  "message": "The block reference must be unique. The reference - HOLD-2024-12-17-0001 already exists.",
  "data": null
}

Error 3: Account Locked/Frozen

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

Error 4: Insufficient Balance

{
  "isSuccessful": false,
  "statusCode": "CBS_402",
  "message": "Insufficient balance to lock the specified amount.",
  "data": null
}

Business Logic

Pre-Conditions

1. Account Validation:

   • Account must exist in the system
   • Account must be in an active state
   • Account must not be frozen or locked

2. Balance Validation:

   • If allowNegativeBalance is false, available balance must be ≥ lock amount
   • Available balance = Account balance - Already blocked amount

3. Uniqueness Validation:

   • Block reference must be unique for the account
   • System checks existing locks before creating new one

Processing Steps

1. Validate Input:

   • Validate account existence and status
   • Check block reference uniqueness
   • Verify account is not frozen or locked

2. Check Balance:

   • If allowNegativeBalance is false, validate sufficient balance
   • Calculate: Available Balance = Account Balance - Blocked Amount

3. Create CBS Transaction:

   • Generate unique transaction key
   • Create transaction record with type AmountLock
   • Set transaction hold state to HOLD

4. Create Amount Lock Record:

   • Store lock details (amount, reference, reason)
   • Link to CBS transaction
   • Set lock state to LOCKED

5. Update Account Balances:

   • Reduce available account balance by lock amount
   • Increase blocked amount by lock amount
   • Note: Actual balance remains unchanged

6. Commit Transaction:

   • Persist all changes atomically
   • Return success response with transaction details

Post-Conditions

• Account Balance: Unchanged
• Available Balance: Reduced by lock amount
• Blocked Amount: Increased by lock amount
• Lock Record: Created with state LOCKED
• CBS Transaction: Created with hold state HOLD

Account Balance Impact

Before Lock:
├── Account Balance: 100,000.00
├── Blocked Amount: 0.00
└── Available Balance: 100,000.00

Lock Operation: 50,000.00

After Lock:
├── Account Balance: 100,000.00 (unchanged)
├── Blocked Amount: 50,000.00 (increased)
└── Available Balance: 50,000.00 (reduced)

Related Operations

Unlock/Release Amount

To remove a lock and restore available balance:

• Command: DeleteDepositLockAmountCommand
• Required: accountEncodedKey, blockReference
• Effect: Restores available balance, removes lock

Seize Locked Amount

To convert locked amount to an actual debit:

• Command: SeizeDepositLockAmountCommand
• Required: accountEncodedKey, blockReference, channelEncodedKey
• Effect: Debits account, removes lock

Query Locks

To retrieve lock information:

• Command: GetLockDepositAmountQuery
• Required: accountEncodedKey
• Effect: Returns list of active/historical locks

Architecture Diagram

Security Considerations

Authorization

• User must have appropriate permissions to lock amounts
• Some lock types (e.g., legal holds) may require elevated permissions
• Audit trail is maintained for all lock operations

Fraud Prevention

• System validates block reference uniqueness to prevent duplicate locks
• Account status checks prevent operations on frozen/locked accounts
• Transaction logging enables forensic analysis

Compliance

• Lock reason field supports regulatory reporting requirements
• All locks are tracked with user details and timestamps
• Supports legal and regulatory hold requirements

Performance Considerations

Database Operations

• Single database transaction for atomicity
• Includes validation queries and insert operations
• Typical response time: 100-300ms

Concurrency

• Uses database transactions for consistency
• Handles concurrent lock requests on same account
• Prevents race conditions through atomic operations

Scalability

• Stateless operation supports horizontal scaling
• Database indexes on account number and block reference
• Suitable for high-volume environments

Troubleshooting

Issue: Duplicate Block Reference Error

Symptom: CBS_409 error even with unique reference

Cause: Previous lock with same reference exists

Solution:

1. Query existing locks: GetLockDepositAmountQuery
2. Check if lock needs to be released
3. Use different block reference if needed

Issue: Insufficient Balance

Symptom: CBS_402 error despite sufficient account balance

Cause: Existing locks reducing available balance

Solution:

1. Check account's blocked amount
2. Review existing locks
3. Release unnecessary locks or reduce lock amount

Issue: Cannot Lock Frozen Account

Symptom: CBS_400 error - account locked/frozen

Cause: Account has operational restrictions

Solution:

1. Verify account status
2. Remove freeze/lock if appropriate
3. Use administrative override if authorized

Monitoring and Alerts

Key Metrics

• Lock success rate
• Average lock duration
• Locks by type/reason
• Unlocked vs seized ratio
• Failed lock attempts

Recommended Alerts

• Locks exceeding 30 days
• Multiple failed lock attempts
• Unusual lock amounts
• High volume of locks on single account

Audit and Compliance

Audit Trail

Every lock operation creates audit records including:

• User who created the lock
• Timestamp of operation
• Account and amount details
• Lock reason
• System and channel information

Regulatory Reporting

Lock data supports:

• Suspicious activity reporting
• Account freeze compliance
• Legal hold documentation
• Financial crime prevention

Code Examples

C# Example

public async Task<CommandExecutionResponse> LockAmount(
    string accountNumber,
    decimal amount,
    string reference,
    string reason)
{
    var request = new BpmExecuteRequest
    {
        CommandName = "LockDepositAmountCommand",
        Data = new Dictionary<string, object>
        {
            { "accountEncodedKey", accountNumber },
            { "blockReference", reference },
            { "amount", amount },
            { "lockReason", reason },
            { "allowNegativeBalance", false }
        }
    };

    var response = await _bpmClient.ExecuteAsync(request);
    return response;
}

JavaScript/TypeScript Example

async function lockDepositAmount(
  accountNumber: string,
  amount: number,
  reference: string,
  reason: string
): Promise<ApiResponse> {
  const response = await fetch('/api/bpm/cmd', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    },
    body: JSON.stringify({
      commandName: 'LockDepositAmountCommand',
      data: {
        accountEncodedKey: accountNumber,
        blockReference: reference,
        amount: amount,
        lockReason: reason,
        allowNegativeBalance: false
      }
    })
  });

  return await response.json();
}

Python Example

import requests

def lock_deposit_amount(account_number, amount, reference, reason):
    url = "https://api.banklingo.com/api/bpm/cmd"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {access_token}"
    }
    payload = {
        "commandName": "LockDepositAmountCommand",
        "data": {
            "accountEncodedKey": account_number,
            "blockReference": reference,
            "amount": amount,
            "lockReason": reason,
            "allowNegativeBalance": False
        }
    }
    
    response = requests.post(url, json=payload, headers=headers)
    return response.json()

Response Codes

Code	Description	Resolution
00	Success	Lock created successfully
CBS_400	Bad Request / Account Locked	Check account status, ensure account is not frozen
CBS_402	Insufficient Balance	Verify available balance, consider allowNegativeBalance option
CBS_404	Account Not Found	Verify account number/encoded key
CBS_409	Duplicate Block Reference	Use unique block reference or query existing locks

Business Rules

Validation Rules

1. Account Encoded Key - Must correspond to an existing, active deposit account in the system
2. Block Reference - Must be unique per account; duplicate references will be rejected with CBS_409 error
3. Amount - Must be a positive decimal value with up to 2 decimal places; zero or negative amounts are not permitted
4. Available Balance - Lock amount cannot exceed available balance unless allowNegativeBalance is set to true
5. Account Status - Account must not be frozen, closed, or have operational restrictions
6. Lock Reason - Maximum 500 characters; used for audit trail and reporting purposes

Operational Rules

1. Locks reduce the available balance but do not affect the actual account balance
2. Multiple locks can exist on the same account with different block references
3. Locks remain active until explicitly released (DeleteDepositLockAmount) or seized (SeizeDepositLockAmount)
4. Setting allowNegativeBalance to true bypasses the available balance check (use with caution)
5. All lock operations are logged in the audit trail with timestamps and user information

Changelog

Version 1.0.0 - December 17, 2025

• Initial documentation
• Added comprehensive request/response examples
• Included code samples in multiple languages
• Added troubleshooting section

---

Last Updated: December 17, 2025

API Version: 1.0

Document Version: 1.0.0