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

using BankLingo.Api.Client;
using BankLingo.Api.Models;

public class DepositAccountService
{
    private readonly IBankLingoClient _client;

    public DepositAccountService(IBankLingoClient client)
    {
        _client = client;
    }

    public async Task<CommanExecutionResponse> CreateDepositAccountAsync(
        string customerId,
        string productId,
        string accountName,
        decimal initialDeposit)
    {
        var command = new CreateDepositCommand
        {
            CustomerId = customerId,
            ProductId = productId,
            AccountName = accountName,
            Currency = "NGN",
            InitialDeposit = initialDeposit,
            BranchId = "BR001",
            RequireApproval = true,
            AdditionalProperties = new Dictionary<string, string>
            {
                { "referenceNumber", $"REF{DateTime.Now:yyyyMMddHHmmss}" },
                { "openingChannel", "Branch" }
            }
        };

        try
        {
            var response = await _client.Deposits.CreateAsync(command);
            
            if (response.Succeeded)
            {
                Console.WriteLine($"Deposit account created: {response.Data.AccountNumber}");
                Console.WriteLine($"Status: {response.Data.Status}");
            }
            else
            {
                Console.WriteLine($"Error: {response.Message}");
                foreach (var error in response.Errors)
                {
                    Console.WriteLine($"- {error.Code}: {error.Message}");
                }
            }

            return response;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Exception: {ex.Message}");
            throw;
        }
    }
}

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

var command = new CreateDepositCommand
{
    CustomerId = "CUST001234",
    ProductId = "PROD-SAVINGS-001",
    AccountName = "John Doe Savings Account",
    Currency = "NGN",
    InitialDeposit = 50000.00,
    BranchId = "BR001",
    RequireApproval = false  // Auto-activate for standard savings
};

2. Opening a Current Account with Approval

var command = new CreateDepositCommand
{
    CustomerId = "CUST001234",
    ProductId = "PROD-CURRENT-001",
    AccountName = "ABC Company Current Account",
    Currency = "NGN",
    InitialDeposit = 100000.00,
    BranchId = "BR001",
    AccountOfficerId = "AO123",
    RequireApproval = true,  // Requires approval for current accounts
    AdditionalProperties = new Dictionary<string, string>
    {
        { "businessType", "Corporate" },
        { "expectedMonthlyTransactions", "High" }
    }
};

3. Opening a Foreign Currency Account

var command = new CreateDepositCommand
{
    CustomerId = "CUST001234",
    ProductId = "PROD-USD-SAVINGS",
    AccountName = "John Doe USD Savings",
    Currency = "USD",
    InitialDeposit = 1000.00,
    BranchId = "BR001",
    AccountOfficerId = "AO123",
    RequireApproval = true,  // Foreign currency accounts typically require approval
    AdditionalProperties = new Dictionary<string, string>
    {
        { "purposeOfAccount", "International Transactions" },
        { "sourceOfFunds", "Business Income" }
    }
};

4. Opening a Zero-Balance Account

var command = new CreateDepositCommand
{
    CustomerId = "CUST001234",
    ProductId = "PROD-BASIC-SAVINGS",
    AccountName = "John Doe Basic Savings",
    Currency = "NGN",
    InitialDeposit = 0.00,  // Zero balance allowed
    BranchId = "BR001",
    RequireApproval = false
};

Integration Examples

Integration with Customer Onboarding Flow

public async Task<CommanExecutionResponse> OnboardCustomerWithDepositAccount(
    CustomerData customerData,
    DepositAccountData accountData)
{
    // Step 1: Create customer
    var createCustomerResponse = await _client.Customers.CreateAsync(new CreateContactCommand
    {
        FirstName = customerData.FirstName,
        LastName = customerData.LastName,
        Email = customerData.Email,
        PhoneNumber = customerData.PhoneNumber
    });

    if (!createCustomerResponse.Succeeded)
    {
        return createCustomerResponse;
    }

    var customerId = createCustomerResponse.Data.ContactId;

    // Step 2: Create deposit account
    var createDepositResponse = await _client.Deposits.CreateAsync(new CreateDepositCommand
    {
        CustomerId = customerId,
        ProductId = accountData.ProductId,
        AccountName = $"{customerData.FirstName} {customerData.LastName} Savings Account",
        Currency = accountData.Currency,
        InitialDeposit = accountData.InitialDeposit,
        BranchId = accountData.BranchId,
        RequireApproval = true
    });

    return createDepositResponse;
}

Integration with Approval Workflow

public async Task<CommanExecutionResponse> CreateDepositWithWorkflow(
    CreateDepositCommand command)
{
    // Create deposit account
    var response = await _client.Deposits.CreateAsync(command);

    if (response.Succeeded && command.RequireApproval)
    {
        // Initiate approval workflow
        var approvalResponse = await _client.Deposits.RequestApprovalAsync(
            new RequestDepositApprovalCommand
            {
                DepositId = response.Data.DepositId,
                Comments = "New deposit account pending approval",
                Priority = "Normal"
            });

        return approvalResponse;
    }

    return response;
}

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​