Get Lock Deposit Amount Query

Query amount locks on a specific deposit account with filtering, pagination, and export capabilities.

Overview

The GetLockDepositAmountQuery retrieves all amount locks for a specific deposit account. It supports filtering by lock state, pagination for large result sets, and Excel export functionality. This query is essential for account management, customer service, and reconciliation workflows.

Key Capabilities

• Account-Specific Query: Retrieves locks for single account
• State Filtering: Option to include or exclude unlocked/seized locks
• Pagination Support: Handles large numbers of locks efficiently
• Excel Export: Export locks to spreadsheet
• Dynamic Filtering: Supports additional filter criteria
• Ordered Results: Returns locks in reverse chronological order
• Complete Lock Details: Includes amounts, states, dates, and references

---

API Endpoint

POST /api/bpm/cmd

---

Request Structure

{
  "commandName": "GetLockDepositAmountQuery",
  "data": {
    "accountEncodedKey": "string",
    "includeUnlocked": "boolean",
    "isExport": "boolean",
    "pageNumber": "integer",
    "pageSize": "integer"
  }
}

Request Fields

Field	Type	Required	Default	Description
accountEncodedKey	string	Yes	-	Account number or encoded key
includeUnlocked	boolean	No	false	Include UNLOCKED and SEIZED locks
isExport	boolean	No	false	Export to Excel instead of JSON
pageNumber	integer	No	1	Page number for pagination
pageSize	integer	No	10	Number of records per page

---

Response Structure

Success Response (Paginated)

{
  "isSuccessful": true,
  "message": "10/25 records returned.",
  "statusCode": "00",
  "data": {
    "items": [
      {
        "id": 12345,
        "blockReference": "CARD-AUTH-20241217-001",
        "lockAmount": 2500.00,
        "lockReason": "Card pre-authorization",
        "currencyCode": "USD",
        "depositAccountNumber": "ACC001234567",
        "state": "LOCKED",
        "transactionKey": "8A3F2D1E9B5C4F7A6E8D2C1B3A9F5E7D",
        "dateCreated": "2024-12-17T10:30:00Z",
        "holdState": "HOLD"
      }
    ],
    "pageNumber": 1,
    "pageSize": 10,
    "totalPages": 3,
    "totalRecords": 25
  },
  "pages": 3,
  "hasNext": true,
  "hasPrevious": false,
  "size": 10,
  "count": 25
}

Export Response

When isExport is true, returns Excel file binary data.

---

Sample Requests

1. Get Active Locks Only (Default)

{
  "commandName": "GetLockDepositAmountQuery",
  "data": {
    "accountEncodedKey": "ACC001234567",
    "pageNumber": 1,
    "pageSize": 20
  }
}

Use Case: Show customer current active locks on their account.

2. Get All Locks (Including History)

{
  "commandName": "GetLockDepositAmountQuery",
  "data": {
    "accountEncodedKey": "ACC001234567",
    "includeUnlocked": true,
    "pageNumber": 1,
    "pageSize": 50
  }
}

Use Case: Full lock history for auditing or investigation.

3. Export Locks to Excel

{
  "commandName": "GetLockDepositAmountQuery",
  "data": {
    "accountEncodedKey": "ACC001234567",
    "includeUnlocked": true,
    "isExport": true
  }
}

Use Case: Generate Excel report of all account locks for compliance.

4. Search with Dynamic Filters

{
  "commandName": "GetLockDepositAmountQuery",
  "data": {
    "accountEncodedKey": "ACC001234567",
    "lockReason": "Card",
    "pageNumber": 1,
    "pageSize": 10
  }
}

Use Case: Find locks matching specific criteria using dynamic predicate builder.

---

Business Logic

Processing Workflow

Query Logic

1. Extract Parameters: Get all filter and pagination parameters
2. Account Validation: Verify account exists
3. Predicate Building:
   • Start with account number match
   • Add dynamic filters from request.Data
   • Add state filter (LOCKED only or all states)
4. Data Retrieval:
   • Include CBSTransaction relationship
   • Order by DateCreated descending (newest first)
   • Apply pagination (skip if export)
5. Response Mapping: Project to simplified model with key fields
6. Export Handling: If isExport, generate Excel using ExcelExporter
7. Success Response: Return paginated results or Excel file

Dynamic Filtering

The query supports dynamic predicate building, allowing filters on any AmountLockTransaction property:

{
  "accountEncodedKey": "ACC001234567",
  "lockAmount_GreaterThan": 1000,
  "dateCreated_After": "2024-01-01",
  "currencyCode": "USD"
}

---

Response Fields

Field	Type	Description
id	integer	Lock transaction ID
blockReference	string	Unique lock reference
lockAmount	decimal	Amount locked
lockReason	string	Reason for lock
currencyCode	string	Currency code
depositAccountNumber	string	Account number
state	string	LOCKED / UNLOCKED / SEIZED
transactionKey	string	Associated transaction key
dateCreated	datetime	Lock creation date/time
holdState	string	HOLD / CANCELLED / SETTLED

---

Error Responses

Error Code	Message	Resolution
Client_Not_Found	"Account not valid"	Verify account identifier

---

Code Examples

C# Implementation

public async Task<LockQueryResponse> GetAccountLocksAsync(
    string accountEncodedKey,
    bool includeUnlocked = false,
    int pageNumber = 1,
    int pageSize = 10)
{
    var request = new
    {
        commandName = "GetLockDepositAmountQuery",
        data = new
        {
            accountEncodedKey,
            includeUnlocked,
            pageNumber,
            pageSize
        }
    };

    var json = JsonSerializer.Serialize(request);
    var content = new StringContent(json, Encoding.UTF8, "application/json");
    var response = await _httpClient.PostAsync($"{_baseUrl}/api/bpm/cmd", content);
    
    return JsonSerializer.Deserialize<LockQueryResponse>(
        await response.Content.ReadAsStringAsync());
}

JavaScript Implementation

async getAccountLocks(
    accountEncodedKey,
    includeUnlocked = false,
    pageNumber = 1,
    pageSize = 10
) {
    const request = {
        commandName: 'GetLockDepositAmountQuery',
        data: {
            accountEncodedKey,
            includeUnlocked,
            pageNumber,
            pageSize
        }
    };

    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();
}

Python Implementation

def get_account_locks(
    self,
    account_encoded_key: str,
    include_unlocked: bool = False,
    page_number: int = 1,
    page_size: int = 10
) -> LockQueryResponse:
    request_data = {
        'commandName': 'GetLockDepositAmountQuery',
        'data': {
            'accountEncodedKey': account_encoded_key,
            'includeUnlocked': include_unlocked,
            'pageNumber': page_number,
            'pageSize': page_size
        }
    }

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

    return response.json()

---

Business Rules

Validation Rules

1. Account Required: accountEncodedKey must be provided
2. Account Must Exist: Account must be in system
3. Valid Page Number: pageNumber must be >= 1
4. Valid Page Size: pageSize must be > 0

Operational Rules

1. Default Behavior: Returns active locks only (LOCKED state)
2. Include Unlocked: Set to true to see full lock history
3. Pagination: Default 10 records per page
4. Ordering: Most recent locks first (descending by DateCreated)
5. Export: isExport bypasses pagination and returns all records
6. Dynamic Filters: Supports additional filter criteria via DynamicPredicateBuilder
7. Eager Loading: Loads CBSTransaction relationship for performance
8. Read-Only: Query does not modify data (disableTracking: true)

---

Related Operations

• LockDepositAmountCommand: Create amount locks
• DeleteDepositLockAmountCommand: Release locks
• SeizeDepositLockAmountCommand: Seize locks
• GetAllCustomerLockDepositAmountQuery: System-wide lock query

---

Support

For technical assistance: api-support@banklingo.com