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

1. 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

2. 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

3. 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

4. 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

5. 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

6. 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

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

Business Validation

1. Customer Status: Customer must not be blacklisted or restricted
2. KYC Compliance: Customer KYC level must meet product requirements
3. Product Availability: Product must be active and available for account opening
4. Currency Support: Currency must be supported by the product and branch
5. Minimum Balance: Initial deposit must meet product's minimum opening balance
6. Branch Capacity: Branch must be operational and accepting new accounts
7. 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

Related Commands

• 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

See Also

• Create Contact - Create customer before opening account
• Deposit Transactions Documentation - Perform transactions on deposit accounts