Skip to main content

Unlock Deposit Account

Unlock a previously locked deposit account to restore transaction capabilities and return the account to its operational state.

Overview​

The UnlockDepositAccountCommand removes an account lock, restoring the account to its previous operational state. This command reverses the effect of LockDepositAccountCommand, allowing deposits, withdrawals, and transfers to resume. It's typically used after investigations are complete, legal holds are lifted, or compliance issues are resolved.

Key Capabilities​

  • Lock Removal: Removes account lock restriction
  • State Restoration: Returns account to previous state before lock
  • Transaction Restoration: Re-enables all transaction types
  • Audit Trail: Records unlock reason and initiating user
  • Validation: Ensures account is actually locked before unlocking
  • Activity Notification: Triggers compliance notifications

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": "UnlockDepositAccountCommand",
  "data": {
    "accountEncodedKey": "string",
    "notes": "string"
  }
}

Request Fields​

FieldTypeRequiredDescriptionValidation
accountEncodedKeystringYesAccount number or encoded key to unlockMust exist and be locked
notesstringNoOptional notes/reason for unlockingFor audit trail

Response Structure​

Success Response​

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

Error Response​

{
  "isSuccessful": false,
  "message": "The deposit account is not presently locked.",
  "statusCode": "INVALID_REQUEST"
}

Sample Requests​

1. Unlock After Investigation Complete​

{
  "commandName": "UnlockDepositAccountCommand",
  "data": {
    "accountEncodedKey": "ACC001234567",
    "notes": "Fraud investigation completed - No fraudulent activity found"
  }
}
{
  "commandName": "UnlockDepositAccountCommand",
  "data": {
    "accountEncodedKey": "8A3F2D1E9B5C4F7A6E8D2C1B3A9F5E7D",
    "notes": "Court order lifted - Case dismissed"
  }
}

3. Unlock After KYC Update​

{
  "commandName": "UnlockDepositAccountCommand",
  "data": {
    "accountEncodedKey": "SAV987654321",
    "notes": "KYC documents updated and verified"
  }
}

Business Logic​

Processing Workflow​

Validation Steps​

  1. Extract Fields: Get accountEncodedKey and optional notes
  2. Account Lookup: Query account with Client and DepositProduct relationships
  3. Existence Check: Verify account exists
  4. Lock Status Check: Verify account is currently in Locked state
  5. State Logic: If PreviousState was also Locked, set it to Active for safety
  6. State Restoration: Set DepositState to PreviousState value
  7. State Sync: Update PreviousState to match current DepositState
  8. Database Update: Persist changes
  9. Notification: Send activity notification with unlock reason
  10. Success Response: Return confirmation

State Management​

Before Unlock:

Account State: Locked
PreviousState: Active (or other pre-lock state)

After Unlock:

Account State: Active (or restored pre-lock state)
PreviousState: Active (synchronized)

Error Responses​

Error CodeMessageScenarioResolution
Client_Not_Found"The deposit account does not exist."Invalid account identifierVerify account number/key
INVALID_REQUEST"The deposit account is not presently locked."Account is not lockedCheck account state first

Code Examples​

C# Implementation​

public async Task<UnlockAccountResponse> UnlockDepositAccountAsync(
    string accountEncodedKey,
    string notes = null)
{
    var request = new
    {
        commandName = "UnlockDepositAccountCommand",
        data = new
        {
            accountEncodedKey,
            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);
    var responseJson = await response.Content.ReadAsStringAsync();
    
    return JsonSerializer.Deserialize<UnlockAccountResponse>(responseJson);
}

JavaScript Implementation​

async unlockDepositAccount(accountEncodedKey, notes = null) {
    const request = {
        commandName: 'UnlockDepositAccountCommand',
        data: {
            accountEncodedKey,
            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 unlock_deposit_account(
    self,
    account_encoded_key: str,
    notes: Optional[str] = None
) -> UnlockAccountResponse:
    request_data = {
        'commandName': 'UnlockDepositAccountCommand',
        'data': {
            'accountEncodedKey': account_encoded_key,
            'notes': notes
        }
    }

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

    result = response.json()
    return UnlockAccountResponse(
        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. Account Must Exist: Account must be in system
  3. Must Be Locked: Account must be in Locked state to unlock
  4. Notes Optional: Unlock notes are optional but recommended

Operational Rules​

  1. State Restoration: Account returns to state it was in before lock
  2. Safety Check: If previous state was also Locked, defaults to Active
  3. Immediate Effect: Transactions can resume immediately after unlock
  4. Activity Logged: Unlock recorded with UnLockDepositAccount action
  5. User Recorded: User who unlocked account is logged
  6. Notification Sent: Activity notification published for audit
  7. Balance Unchanged: Account balance unaffected by unlock operation
  • LockDepositAccountCommand: Lock an account
  • ActivatePNDOnAccountCommand: Apply debit restriction instead of full lock
  • GetAccountDetailsQuery: Check account state before unlocking

Support​

For technical assistance: api-support@banklingo.com