Close Deposit Account

Overview

The CloseDepositCommand allows authorized users to close a deposit account, making it inactive and preventing future transactions.

Endpoint

POST /api/bpm/cmd

Request Body

{
  "cmd": "CloseDepositCommand",
  "data": {
    "accountEncodedKey": "DEP-123456",
    "closureType": "ClientRequested",
    "comment": "Account closure as per customer request"
  }
}

Request Parameters

Parameter	Type	Required	Description
cmd	string	Yes	Must be "CloseDepositCommand"
data	object	Yes	Closure data
↳ accountEncodedKey	string	Yes	Deposit account identifier
↳ closureType	string	Yes	Type of closure (ClientRequested, Dormant, etc.)
↳ comment	string	No	Closure reason/comment

## Response Structure

### Success Response

```json
{
  "succeeded": true,
  "message": "Deposit account closed successfully",
  "data": {
    "depositId": "DEP001234",
    "accountNumber": "1234567890",
    "status": "Closed",
    "closingBalance": 250000.00,
    "transferToAccountNumber": "9876543210",
    "closedBy": "user@bank.com",
    "closedDate": "2024-01-16T15:00:00Z",
    "closureReason": "Customer request - Account consolidation"
  },
  "statusCode": 200
}

Error Response

{
  "succeeded": false,
  "message": "Failed to close deposit account",
  "errors": [
    {
      "code": "OUTSTANDING_BALANCE",
      "message": "Account has outstanding balance that must be transferred",
      "field": "depositId"
    }
  ],
  "statusCode": 400
}

Field Descriptions

Field	Type	Required	Description
depositId	string	Yes	Unique identifier of the deposit account to close
closureReason	string	Yes	Reason for closing the account
transferToAccountNumber	string	Conditional	Account to transfer remaining balance (required if balance > 0)

Business Rules

1. Balance Requirements

   • If account has a positive balance, must specify transfer account
   • Cannot close account with negative balance
   • All pending transactions must be cleared

2. Authorization

   • User must have permission to close accounts
   • Some account types may require approval before closure

3. Account Status

   • Account must be in "Active" or "Dormant" status
   • Cannot close already closed accounts

4. Transfer Account Validation

   • Transfer account must exist and be active
   • Transfer account must belong to the same customer
   • Transfer account must support the currency

5. Post-Closure

   • Account status changed to "Closed"
   • No further transactions allowed
   • Account retained for historical records

Error Codes

Code	Description	HTTP Status
DEPOSIT_NOT_FOUND	Deposit account does not exist	404
OUTSTANDING_BALANCE	Account has balance requiring transfer	400
INVALID_TRANSFER_ACCOUNT	Transfer account is invalid	400
PENDING_TRANSACTIONS	Account has pending transactions	400
ALREADY_CLOSED	Account is already closed	400
INSUFFICIENT_PERMISSIONS	User does not have closure permission	403
INTERNAL_ERROR	An unexpected error occurred	500

Code Examples

C# Example

public async Task<CommanExecutionResponse> CloseDepositAccountAsync(
    string depositId,
    string reason,
    string transferToAccount = null)
{
    var command = new CloseDepositCommand
    {
        DepositId = depositId,
        ClosureReason = reason,
        TransferToAccountNumber = transferToAccount
    };

    var response = await _client.Deposits.CloseAsync(command);
    
    if (response.Succeeded)
    {
        Console.WriteLine($"Deposit account closed: {response.Data.AccountNumber}");
        Console.WriteLine($"Closing Balance: {response.Data.ClosingBalance:N2}");
        
        if (!string.IsNullOrEmpty(response.Data.TransferToAccountNumber))
        {
            Console.WriteLine($"Balance transferred to: {response.Data.TransferToAccountNumber}");
        }
    }

    return response;
}

JavaScript/TypeScript Example

async closeDepositAccount(
  depositId: string,
  reason: string,
  transferToAccount?: string
) {
  const command = {
    depositId,
    closureReason: reason,
    transferToAccountNumber: transferToAccount
  };

  const response = await this.client.deposits.close(command);
  
  if (response.succeeded) {
    console.log(`Deposit account closed: ${response.data.accountNumber}`);
    console.log(`Closing Balance: ${response.data.closingBalance.toFixed(2)}`);
    
    if (response.data.transferToAccountNumber) {
      console.log(`Balance transferred to: ${response.data.transferToAccountNumber}`);
    }
  }

  return response;
}

cURL Example

curl -X POST https://api.banklingo.com/api/administration/deposits/close \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "depositId": "DEP001234",
    "closureReason": "Customer request - Account consolidation",
    "transferToAccountNumber": "9876543210"
  }'

Common Use Cases

1. Close Zero-Balance Account

var command = new CloseDepositCommand
{
    DepositId = "DEP001234",
    ClosureReason = "Customer request - No longer needed"
    // No transfer account needed for zero balance
};

2. Close Account with Balance Transfer

var command = new CloseDepositCommand
{
    DepositId = "DEP001234",
    ClosureReason = "Account consolidation",
    TransferToAccountNumber = "9876543210"  // Balance will be transferred here
};

3. Close Dormant Account

var command = new CloseDepositCommand
{
    DepositId = "DEP001234",
    ClosureReason = "Dormant account - Inactive for over 2 years",
    TransferToAccountNumber = "9876543210"
};

Integration Examples

Complete Account Closure Workflow

public async Task<CommanExecutionResponse> PerformAccountClosureAsync(
    string depositId,
    string reason,
    string transferToAccount)
{
    // Step 1: Get account details
    var accountResponse = await _client.Deposits.GetByIdAsync(
        new RetrieveDepositByIdQuery { DepositId = depositId });
    
    if (!accountResponse.Succeeded)
    {
        return accountResponse;
    }

    var account = accountResponse.Data;

    // Step 2: Check for pending transactions
    var transactionsResponse = await _client.Deposits.GetTransactionsAsync(
        new RetrieveDepositTransactionListQuery 
        { 
            DepositId = depositId,
            PageNumber = 1,
            PageSize = 10
        });

    // Step 3: Close the account
    var closeResponse = await _client.Deposits.CloseAsync(new CloseDepositCommand
    {
        DepositId = depositId,
        ClosureReason = reason,
        TransferToAccountNumber = account.Balance > 0 ? transferToAccount : null
    });

    return closeResponse;
}

Notes

• Permanent Action: Account closure is typically permanent and cannot be easily reversed
• Historical Data: Closed accounts remain in the system for historical and compliance purposes
• Balance Transfer: Automatic balance transfer is executed as part of the closure process
• Notifications: System sends closure confirmation to customer and account officer
• Regulatory Compliance: Closure must comply with banking regulations and customer agreement terms
• Audit Trail: All closure operations are logged with detailed audit information

Related Commands

• Create Deposit Account - Create new deposit account
• Update Deposit Account - Modify deposit account information
• Retrieve Deposit By ID - Get deposit account details
• Retrieve Deposit Transaction List - View account transactions

See Also

• Deposit Transactions Documentation - Transaction operations