Delete Lock Amount

Release a previously locked amount on a deposit account, returning the funds to the available balance.

Overview

The DeleteDepositLockAmountCommand removes an amount lock from a deposit account, releasing the blocked funds back to the available balance. This command reverses a LockDepositAmountCommand when the lock is no longer needed (e.g., card pre-authorization expired, hold released, pending transaction cancelled).

Key Capabilities

• Lock Release: Removes amount lock and restores funds
• Balance Restoration: Returns locked amount to available balance
• Transaction Cancellation: Marks lock transaction as CANCELLED
• Duplicate Prevention: Uses unique block reference for idempotency
• Atomic Operation: Uses database transaction for consistency
• Audit Trail: Records release reason and user

---

API Endpoint

POST /api/bpm/cmd

---

Request Structure

{
  "commandName": "DeleteDepositLockAmountCommand",
  "data": {
    "accountEncodedKey": "string",
    "blockReference": "string",
    "notes": "string"
  }
}

Request Fields

Field	Type	Required	Description
accountEncodedKey	string	Yes	Account number or encoded key
blockReference	string	Yes	Unique reference from original lock
notes	string	No	Optional notes/reason for release

---

Response Structure

Success Response

{
  "isSuccessful": true,
  "message": "Amount lock has been released successfully.",
  "statusCode": "00"
}

Error Response

{
  "isSuccessful": false,
  "message": "There is no existing amount lock with the specified reference",
  "statusCode": "Client_Not_Found"
}

---

Sample Requests

1. Release Card Pre-Authorization

{
  "commandName": "DeleteDepositLockAmountCommand",
  "data": {
    "accountEncodedKey": "ACC001234567",
    "blockReference": "CARD-AUTH-20241217-001",
    "notes": "Card pre-authorization expired - Amount released"
  }
}

2. Cancel Hotel Hold

{
  "commandName": "DeleteDepositLockAmountCommand",
  "data": {
    "accountEncodedKey": "SAV987654321",
    "blockReference": "HOTEL-HOLD-5678",
    "notes": "Hotel checkout completed - Hold released"
  }
}

3. Release Legal Hold

{
  "commandName": "DeleteDepositLockAmountCommand",
  "data": {
    "accountEncodedKey": "8A3F2D1E9B5C4F7A6E8D2C1B3A9F5E7D",
    "blockReference": "LEGAL-HOLD-2024-123",
    "notes": "Court order lifted - Amount released"
  }
}

---

Business Logic

Processing Workflow

Validation Steps

1. Extract Fields: Get accountEncodedKey, blockReference, notes
2. Account Query: Load account with relationships
3. Account Validation: Verify account exists
4. Lock Query: Find lock with matching blockReference and LOCKED state
5. Lock Validation: Verify lock exists and is active (HOLD state)
6. Transaction Begin: Start database transaction for atomicity
7. State Updates:
   • Set lock transaction to CANCELLED
   • Set lock state to UNLOCKED
8. Balance Updates:
   • Add lock amount to AccountBalance
   • Subtract from BlockedAmount
9. Persist Changes: Update all records
10. Commit: Commit database transaction
11. Notification: Send activity notification
12. Success Response: Return confirmation

Balance Impact

Before Delete:

AccountBalance: 10,000.00
BlockedAmount: 2,000.00
Available: 8,000.00

After Delete (2,000 lock removed):

AccountBalance: 12,000.00
BlockedAmount: 0.00
Available: 12,000.00

---

Error Responses

Error Code	Message	Scenario	Resolution
Client_Not_Found	"Account not valid"	Invalid account identifier	Verify account number/key
Client_Not_Found	"No lock with reference"	Lock not found or already released	Verify blockReference is correct

---

Code Examples

C# Implementation

public async Task<DeleteLockResponse> DeleteLockAmountAsync(
    string accountEncodedKey,
    string blockReference,
    string notes = null)
{
    var request = new
    {
        commandName = "DeleteDepositLockAmountCommand",
        data = new
        {
            accountEncodedKey,
            blockReference,
            notes
        }
    };

    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<DeleteLockResponse>(
        await response.Content.ReadAsStringAsync());
}

JavaScript Implementation

async deleteLockAmount(accountEncodedKey, blockReference, notes = null) {
    const request = {
        commandName: 'DeleteDepositLockAmountCommand',
        data: {
            accountEncodedKey,
            blockReference,
            notes
        }
    };

    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 delete_lock_amount(
    self,
    account_encoded_key: str,
    block_reference: str,
    notes: Optional[str] = None
) -> DeleteLockResponse:
    request_data = {
        'commandName': 'DeleteDepositLockAmountCommand',
        'data': {
            'accountEncodedKey': account_encoded_key,
            'blockReference': block_reference,
            'notes': notes
        }
    }

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

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

---

Business Rules

Validation Rules

1. Account Required: accountEncodedKey must be provided
2. Block Reference Required: blockReference must match existing lock
3. Account Must Exist: Account must be in system
4. Lock Must Exist: Lock with blockReference must exist
5. Lock Must Be Active: Lock state must be LOCKED (not already UNLOCKED or SEIZED)
6. Transaction Hold State: Transaction must be in HOLD state

Operational Rules

1. Atomic Operation: Uses database transaction to ensure consistency
2. State Changes: Lock state → UNLOCKED, Transaction state → CANCELLED
3. Balance Restoration: Locked amount returned to available balance
4. Blocked Amount: Decreased by lock amount
5. Activity Logged: Release logged with UnLockDepositAmount action
6. Notification: Includes block reference, amount, and currency
7. Rollback on Error: Transaction rolled back if any error occurs
8. Idempotent: Cannot delete same lock twice
9. No Fee: Lock deletion does not incur charges
10. Immediate Effect: Funds available immediately after release

---

Related Operations

• LockDepositAmountCommand: Create amount lock
• SeizeDepositLockAmountCommand: Convert lock to debit (instead of releasing)
• GetLockDepositAmountQuery: Query account locks before deleting

---

Troubleshooting

Issue: Lock Not Found

Symptom: "No existing amount lock with the specified reference"

Possible Causes:

1. Incorrect blockReference
2. Lock already deleted/seized
3. Lock belongs to different account

Solution:

• Use GetLockDepositAmountQuery to verify lock exists
• Confirm blockReference matches exactly
• Check lock state (must be LOCKED)

---

Support

For technical assistance: api-support@banklingo.com