Create Deposit Account

Overview

The CreateDepositCommand allows you to create a new deposit account in the banking system. This command initializes a deposit account with customer information, account type, product details, and initial configuration settings.

Endpoint

POST /api/bpm/cmd

Request Body

{
  "cmd": "CreateDepositCommand",
  "data": {
    "accountInformation": {
      "depositProductEncodedKey": "PROD-SAV-001",
      "clientEncodedKey": "CLI-123456",
      "interestRate": 5.5,
      "recommendedDepositAmount": 10000.00,
      "maximumWithdrawalAmount": 50000.00,
      "accountTierId": 1,
      "notes": "New savings account",
      "sourceAccount": "ACC-987654"
    },
    "signatoryInformation": [
      {
        "clientEncodedKey": "CLI-123456",
        "role": "Primary",
        "signatoryType": "Single"
      }
    ],
    "tags": ["savings", "retail"],
    "salesChannelCode": "BRANCH"
  }
}

Request Parameters

Parameter	Type	Required	Description
cmd	string	Yes	Must be `"CreateDepositCommand"`
data	object	Yes	Deposit account creation data
â†³ accountInformation	object	Yes	Account details
â†³ depositProductEncodedKey	string	Yes	Product identifier
â†³ clientEncodedKey	string	Yes	Client identifier
â†³ interestRate	decimal	Yes	Interest rate percentage
â†³ recommendedDepositAmount	decimal	No	Suggested deposit amount
â†³ maximumWithdrawalAmount	decimal	No	Maximum withdrawal limit
â†³ accountTierId	integer	No	Account tier identifier
â†³ notes	string	No	Additional notes
â†³ sourceAccount	string	No	Source account reference
â†³ signatoryInformation	array	Yes	List of account signatories (at least one required)
â†³ clientEncodedKey	string	Yes	Signatory client identifier
â†³ role	string	Yes	Signatory role (Primary, Secondary)
â†³ signatoryType	string	Yes	Type (Single, Joint)
â†³ tags	array	No	Account tags for categorization
â†³ salesChannelCode	string	No	Sales channel identifier

## Response Structure

### Success Response

```json
{
  "succeeded": true,
  "message": "Deposit account created successfully",
  "data": {
    "depositId": "DEP001234",
    "accountNumber": "1234567890",
    "accountName": "John Doe Savings Account",
    "customerId": "CUST001234",
    "productId": "PROD-SAVINGS-001",
    "currency": "NGN",
    "balance": 50000.00,
    "status": "Pending_Approval",
    "branchId": "BR001",
    "accountOfficerId": "AO123",
    "createdDate": "2024-01-15T10:30:00Z",
    "createdBy": "user@bank.com"
  },
  "statusCode": 201
}

Error Response

{
  "succeeded": false,
  "message": "Failed to create deposit account",
  "errors": [
    {
      "code": "INVALID_CUSTOMER",
      "message": "Customer with ID CUST001234 does not exist",
      "field": "customerId"
    },
    {
      "code": "INVALID_PRODUCT",
      "message": "Product with ID PROD-SAVINGS-001 is not active",
      "field": "productId"
    }
  ],
  "statusCode": 400
}

Field Descriptions

Field	Type	Required	Description
`customerId`	string	Yes	Unique identifier of the customer opening the deposit account
`productId`	string	Yes	Unique identifier of the deposit product (e.g., savings, current account)
`accountName`	string	Yes	Display name for the deposit account
`accountNumber`	string	No	Custom account number (auto-generated if not provided)
`currency`	string	Yes	ISO currency code (NGN, USD, EUR, GBP, etc.)
`initialDeposit`	decimal	No	Initial deposit amount (may be 0 based on product configuration)
`branchId`	string	Yes	Branch where the account is opened
`accountOfficerId`	string	No	Account officer responsible for managing this account
`requireApproval`	boolean	No	Whether account requires approval before activation (default: false)
`additionalProperties`	object	No	Additional custom properties or metadata

Business Rules

Customer Validation
- Customer must exist and be active in the system
- Customer must not be blacklisted
- Customer must pass KYC requirements based on product configuration
Product Validation
- Deposit product must exist and be active
- Product must be available for the selected currency
- Customer must meet minimum balance requirements if specified
Account Number Generation
- If not provided, account number is auto-generated based on bank's numbering scheme
- Account number must be unique across all deposit accounts
- Account number format must comply with product configuration
Initial Deposit
- Must meet minimum opening balance requirements if specified in product
- Must be greater than or equal to zero
- Currency must match the account currency
Approval Workflow
- If requireApproval is true, account status will be "Pending_Approval"
- If requireApproval is false, account is immediately activated
- Approval requirement may be enforced by product configuration
Branch and Officer Assignment
- Branch must exist and be active
- Account officer (if provided) must be assigned to the specified branch
- Account officer must have appropriate permissions

Error Codes

Code	Description	HTTP Status
`INVALID_CUSTOMER`	Customer does not exist or is inactive	400
`CUSTOMER_BLACKLISTED`	Customer is blacklisted and cannot open new accounts	400
`INVALID_PRODUCT`	Deposit product does not exist or is inactive	400
`DUPLICATE_ACCOUNT_NUMBER`	Account number already exists	400
`INSUFFICIENT_INITIAL_DEPOSIT`	Initial deposit is below minimum required amount	400
`CURRENCY_NOT_SUPPORTED`	Currency is not supported by the deposit product	400
`INVALID_BRANCH`	Branch does not exist or is inactive	400
`INVALID_ACCOUNT_OFFICER`	Account officer does not exist or is not assigned to branch	400
`KYC_INCOMPLETE`	Customer KYC requirements are not met	400
`VALIDATION_ERROR`	One or more validation errors occurred	400
`UNAUTHORIZED`	User does not have permission to create deposit accounts	403
`INTERNAL_ERROR`	An unexpected error occurred	500

Code Examples

C# Example

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

JavaScript/TypeScript Example

import { BankLingoClient, CreateDepositCommand } from '@banklingo/api-client';

class DepositAccountService {
  private client: BankLingoClient;

  constructor(client: BankLingoClient) {
    this.client = client;
  }

  async createDepositAccount(
    customerId: string,
    productId: string,
    accountName: string,
    initialDeposit: number
  ) {
    const command: CreateDepositCommand = {
      customerId,
      productId,
      accountName,
      currency: 'NGN',
      initialDeposit,
      branchId: 'BR001',
      requireApproval: true,
      additionalProperties: {
        referenceNumber: `REF${Date.now()}`,
        openingChannel: 'Branch'
      }
    };

    try {
      const response = await this.client.deposits.create(command);
      
      if (response.succeeded) {
        console.log(`Deposit account created: ${response.data.accountNumber}`);
        console.log(`Status: ${response.data.status}`);
      } else {
        console.log(`Error: ${response.message}`);
        response.errors.forEach(error => {
          console.log(`- ${error.code}: ${error.message}`);
        });
      }

      return response;
    } catch (error) {
      console.error('Exception:', error);
      throw error;
    }
  }
}

cURL Example

curl -X POST https://api.banklingo.com/api/administration/deposits/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "customerId": "CUST001234",
    "productId": "PROD-SAVINGS-001",
    "accountName": "John Doe Savings Account",
    "currency": "NGN",
    "initialDeposit": 50000.00,
    "branchId": "BR001",
    "accountOfficerId": "AO123",
    "requireApproval": true,
    "additionalProperties": {
      "referenceNumber": "REF20240115001",
      "openingChannel": "Branch"
    }
  }'

Common Use Cases

1. Opening a Savings Account

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

2. Opening a Current Account with Approval

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

3. Opening a Foreign Currency Account

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

4. Opening a Zero-Balance Account

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Integration Examples

Integration with Customer Onboarding Flow

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Integration with Approval Workflow

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Validation Rules

Request Validation

CustomerId: Required, must exist and be active
ProductId: Required, must exist and be active
AccountName: Required, maximum 100 characters
AccountNumber: Optional, if provided must be unique and follow bank's format
Currency: Required, must be valid ISO currency code (3 characters)
InitialDeposit: Optional, must be greater than or equal to 0 and less than or equal to maximum initial deposit limit
BranchId: Required, must exist and be active
AccountOfficerId: Optional, if provided must exist and be assigned to branch

Business Validation

Customer Status: Customer must not be blacklisted or restricted
KYC Compliance: Customer KYC level must meet product requirements
Product Availability: Product must be active and available for account opening
Currency Support: Currency must be supported by the product and branch
Minimum Balance: Initial deposit must meet product's minimum opening balance
Branch Capacity: Branch must be operational and accepting new accounts
Duplicate Account Prevention: System checks for existing accounts with same customer and product combination

Notes

Account Status: Newly created accounts have status "Pending_Approval" if approval is required, otherwise "Active"
Account Number: If not provided, system auto-generates based on bank's configuration
Idempotency: Multiple requests with same data may create duplicate accounts; use reference numbers to prevent this
Audit Trail: All deposit account creation operations are logged for audit purposes
Notifications: System sends notifications to customer and account officer upon successful creation
Maker-Checker: If approval is required, a separate approval step must be completed before account is activated

Update Deposit Account - Modify deposit account information
Retrieve Deposit List - Get list of deposit accounts
Retrieve Deposit By ID - Get specific deposit account details
Request Deposit Approval - Submit deposit account for approval
Approve Deposit - Approve pending deposit account
Reject Deposit - Reject pending deposit account
Close Deposit - Close deposit account

Overview​

Endpoint​

Request Body​

Request Parameters​

Error Response​

Field Descriptions​

Business Rules​

Error Codes​

Code Examples​

C# Example​

JavaScript/TypeScript Example​

cURL Example​

Common Use Cases​

1. Opening a Savings Account​

2. Opening a Current Account with Approval​

3. Opening a Foreign Currency Account​

4. Opening a Zero-Balance Account​

Integration Examples​

Integration with Customer Onboarding Flow​

Integration with Approval Workflow​

Validation Rules​

Request Validation​

Business Validation​

Notes​

Related Commands​

See Also​

Overview

Endpoint

Request Body

Request Parameters

Error Response

Field Descriptions

Business Rules

Error Codes

Code Examples

C# Example

JavaScript/TypeScript Example

cURL Example

Common Use Cases

1. Opening a Savings Account

2. Opening a Current Account with Approval

3. Opening a Foreign Currency Account

4. Opening a Zero-Balance Account

Integration Examples

Integration with Customer Onboarding Flow

Integration with Approval Workflow

Validation Rules

Request Validation

Business Validation

Notes

Related Commands

See Also