Create Loan Account

Overview

Creates a new loan account in the banking system with specified terms, collateral, and guarantor information.

Endpoint

POST /api/bpm/cmd

Request Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be application/json
X-Tenant-Id	string	Yes	Tenant identifier

Request Body

{
  "cmd": "CreateLoanCommand",
  "data": {
    "accountName": "Business Loan - ABC Company",
    "associationInformation": {
      "accountOfficerEncodedKey": "8a8e8e8e7f0000017f0000000001",
      "branchEncodedKey": "8a8e8e8e7f0000017f0000000002",
      "clientEncodedKey": "CUST-12345",
      "productEncodedKey": "PROD-BUS-001"
    },
    "accountInformation": {
      "loanAmount": 500000.00,
      "interestRate": 15.5,
      "loanTenor": 24,
      "notes": "Working capital loan",
      "firstRepaymentDate": "2024-02-15T00:00:00Z",
      "moratoriumType": 0,
      "moratoriumPeriod": 0
    },
    "disbursementInformation": {
      "disbursementDate": "2024-01-15T00:00:00Z",
      "disbursementMethod": "BankTransfer",
      "disbursmentChannelEncodedKey": "8a8e8e8e7f0000017f0000000003"
    },
    "comments": ["Initial loan application", "Approved by credit committee"],
    "tags": ["business", "working-capital"],
    "salesChannelCode": "BRANCH"
  }
}

Request Parameters

Parameter	Type	Required	Description
accountName	string	Yes	Name/title of the loan account
associationInformation	object	Yes	Links loan to customer, product, branch, and officer
↳ accountOfficerEncodedKey	string	Yes	Unique identifier of the loan officer
↳ branchEncodedKey	string	Yes	Branch where loan is originated
↳ clientEncodedKey	string	Yes	Customer/client identifier
↳ productEncodedKey	string	Yes	Loan product type identifier
accountInformation	object	Yes	Core loan terms and amounts
↳ loanAmount	decimal	Yes	Principal loan amount
↳ interestRate	decimal	Yes	Annual interest rate (percentage)
↳ loanTenor	integer	Yes	Loan duration in months
↳ notes	string	No	Additional notes or comments
↳ firstRepaymentDate	datetime	No	Date of first repayment
↳ moratoriumType	integer	Yes	Type of moratorium (0=None, 1=Principal, 2=Interest, 3=Both)
↳ moratoriumPeriod	integer	Yes	Moratorium period in months
disbursementInformation	object	Yes	MANDATORY - Disbursement details
↳ disbursementDate	datetime	Yes	When funds will be disbursed
↳ disbursementMethod	string	Yes	Method: "BankTransfer", "Cash", "Cheque"
↳ disbursmentChannelEncodedKey	string	No	Disbursement account/channel identifier
comments	array[string]	No	Array of comment strings
tags	array[string]	No	Array of tag strings for categorization
salesChannelCode	string	No	Sales channel identifier

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Loan account created successfully",
  "data": {
    "loanId": "LA-2024-00001",
    "loanAccountNumber": "3001234567890",
    "customerId": "CUST-12345",
    "loanAmount": 50000.00,
    "interestRate": 12.5,
    "loanTerm": 24,
    "monthlyPayment": 2368.75,
    "totalInterest": 6850.00,
    "totalRepayable": 56850.00,
    "status": "PendingApproval",
    "disbursementDate": "2024-01-15T00:00:00Z",
    "repaymentStartDate": "2024-02-15T00:00:00Z",
    "maturityDate": "2026-01-15T00:00:00Z",
    "createdAt": "2024-01-10T14:30:00Z",
    "createdBy": "user@bank.com"
  }
}

Error Response (400 Bad Request)

{
  "success": false,
  "message": "Loan creation failed",
  "errors": [
    {
      "field": "customerId",
      "message": "Customer not found or not eligible for loan"
    },
    {
      "field": "loanAmount",
      "message": "Loan amount exceeds maximum allowed for this product"
    }
  ]
}

Status Codes

Code	Description
200	Loan account created successfully
400	Invalid request data or business rule violation
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Customer or loan product not found
409	Conflict - Duplicate loan application exists
500	Internal server error

Business Rules

Loan Creation Rules

1. Customer Eligibility

   • Customer must have active status
   • Customer must pass credit worthiness checks
   • Customer must meet minimum age requirements
   • Customer cannot have defaulted loans

2. Loan Amount Validation

   • Must be within product minimum/maximum limits
   • Must not exceed customer's borrowing capacity
   • Must align with collateral value requirements
   • Must be positive and non-zero

3. Interest Rate Rules

   • Must be within product rate range
   • Cannot be negative
   • Must comply with regulatory caps
   • May vary based on customer risk profile

4. Term and Schedule Rules

   • Loan term must be within product limits
   • Repayment frequency must match product settings
   • First repayment date must be after disbursement
   • Maturity date calculated from term and frequency

5. Collateral Requirements

   • Secured loans must have collateral specified
   • Collateral value must meet loan-to-value ratios
   • Collateral must be properly documented
   • Multiple collateral items can be linked

6. Guarantor Rules

   • Guarantors must be existing customers
   • Guarantors must have good credit standing
   • Total guarantee must meet product requirements
   • Guarantor cannot be the borrower

7. Approval Workflow

   • New loans start in PendingApproval status
   • Approval required before disbursement
   • Multiple approval levels may be required
   • Loan amount may trigger different approval tiers

Code Examples

C# Example

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class LoanService
{
    private readonly HttpClient _httpClient;
    
    public async Task<LoanResponse> CreateLoanAsync(object loanData)
    {
        var commandRequest = new
        {
            cmd = "CreateLoanCommand",
            data = loanData
        };
        
        var json = JsonSerializer.Serialize(commandRequest);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await _httpClient.PostAsync(
            "/api/bpm/cmd", 
            content
        );
        
        response.EnsureSuccessStatusCode();
        
        var responseJson = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize<LoanResponse>(responseJson);
    }
}

// Usage
var loanData = new
{
    accountName = "Business Loan - ABC Company",
    associationInformation = new
    {
        accountOfficerEncodedKey = "8a8e8e8e7f0000017f0000000001",
        branchEncodedKey = "8a8e8e8e7f0000017f0000000002",
        clientEncodedKey = "CUST-12345",
        productEncodedKey = "PROD-BUS-001"
    },
    accountInformation = new
    {
        loanAmount = 500000.00m,
        interestRate = 15.5m,
        loanTenor = 24,
        notes = "Working capital loan for inventory purchase",
        firstRepaymentDate = DateTime.Parse("2024-02-15"),
        moratoriumType = 0,
        moratoriumPeriod = 0
    },
    disbursementInformation = new
    {
        disbursementDate = DateTime.Parse("2024-01-15"),
        disbursementMethod = "BankTransfer",
        disbursmentChannelEncodedKey = "8a8e8e8e7f0000017f0000000003"
    },
    comments = new[] { "Initial loan application", "Fast-track requested" },
    tags = new[] { "business", "working-capital" },
    salesChannelCode = "BRANCH"
};

var result = await loanService.CreateLoanAsync(loanData);
Console.WriteLine($"Loan created: {result.Data.LoanId}");

TypeScript/JavaScript Example

interface LoanCommandRequest {
  cmd: string;
  data: {
    accountName: string;
    associationInformation: {
      accountOfficerEncodedKey: string;
      branchEncodedKey: string;
      clientEncodedKey: string;
      productEncodedKey: string;
    };
    accountInformation: {
      loanAmount: number;
      interestRate: number;
      loanTenor: number;
      notes?: string;
      firstRepaymentDate?: string;
      moratoriumType: number;
      moratoriumPeriod: number;
    };
    disbursementInformation: {
      disbursementDate: string;
      disbursementMethod: string;
      disbursmentChannelEncodedKey?: string;
    };
    comments?: string[];
    tags?: string[];
    salesChannelCode?: string;
  };
}

async function createLoan(loanData: LoanCommandRequest['data']): Promise<any> {
  const commandRequest: LoanCommandRequest = {
    cmd: 'CreateLoanCommand',
    data: loanData
  };
  
  const response = await fetch('/api/bpm/cmd', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`,
      'X-Tenant-Id': tenantId
    },
    body: JSON.stringify(commandRequest)
  });
  
  if (!response.ok) {
    throw new Error(`Loan creation failed: ${response.statusText}`);
  }
  
  return await response.json();
}

// Usage
const loanData = {
  accountName: 'Business Loan - ABC Company',
  associationInformation: {
    accountOfficerEncodedKey: '8a8e8e8e7f0000017f0000000001',
    branchEncodedKey: '8a8e8e8e7f0000017f0000000002',
    clientEncodedKey: 'CUST-12345',
    productEncodedKey: 'PROD-BUS-001'
  },
  accountInformation: {
    loanAmount: 500000.00,
    interestRate: 15.5,
    loanTenor: 24,
    notes: 'Working capital loan for inventory purchase',
    firstRepaymentDate: '2024-02-15T00:00:00Z',
    moratoriumType: 0,
    moratoriumPeriod: 0
  },
  disbursementInformation: {
    disbursementDate: '2024-01-15T00:00:00Z',
    disbursementMethod: 'BankTransfer',
    disbursmentChannelEncodedKey: '8a8e8e8e7f0000017f0000000003'
  },
  comments: ['Initial loan application', 'Fast-track requested'],
  tags: ['business', 'working-capital'],
  salesChannelCode: 'BRANCH'
};

const result = await createLoan(loanData);
console.log('Loan created:', result.data.loanId);

cURL Example

curl -X POST https://api.yourbank.com/api/bpm/cmd \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-Id: YOUR_TENANT_ID" \
  -d '{
    "cmd": "CreateLoanCommand",
    "data": {
      "accountName": "Business Loan - ABC Company",
      "associationInformation": {
        "accountOfficerEncodedKey": "8a8e8e8e7f0000017f0000000001",
        "branchEncodedKey": "8a8e8e8e7f0000017f0000000002",
        "clientEncodedKey": "CUST-12345",
        "productEncodedKey": "PROD-BUS-001"
      },
      "accountInformation": {
        "loanAmount": 500000.00,
        "interestRate": 15.5,
        "loanTenor": 24,
        "notes": "Working capital loan for inventory purchase",
        "firstRepaymentDate": "2024-02-15T00:00:00Z",
        "moratoriumType": 0,
        "moratoriumPeriod": 0
      },
      "disbursementInformation": {
        "disbursementDate": "2024-01-15T00:00:00Z",
        "disbursementMethod": "BankTransfer",
        "disbursmentChannelEncodedKey": "8a8e8e8e7f0000017f0000000003"
      },
      "comments": ["Initial loan application", "Fast-track requested"],
      "tags": ["business", "working-capital"],
      "salesChannelCode": "BRANCH"
    }
  }'

Common Use Cases

Personal Loan Application

Creating a personal loan with minimal required fields:

{
  "cmd": "CreateLoanCommand",
  "data": {
    "accountName": "Personal Loan - John Doe",
    "associationInformation": {
      "accountOfficerEncodedKey": "8a8e8e8e7f0000017f0000000001",
      "branchEncodedKey": "8a8e8e8e7f0000017f0000000002",
      "clientEncodedKey": "CUST-12345",
      "productEncodedKey": "PROD-PERSONAL-001"
    },
    "accountInformation": {
      "loanAmount": 25000.00,
      "interestRate": 18.0,
      "loanTenor": 12,
      "notes": "Home renovation",
      "moratoriumType": 0,
      "moratoriumPeriod": 0
    },
    "disbursementInformation": {
      "disbursementDate": "2024-02-01T00:00:00Z",
      "disbursementMethod": "BankTransfer"
    }
  }
}

Secured Business Loan with Moratorium

Creating a business loan with a grace period before repayments start:

{
  "cmd": "CreateLoanCommand",
  "data": {
    "accountName": "Equipment Financing - XYZ Ltd",
    "associationInformation": {
      "accountOfficerEncodedKey": "8a8e8e8e7f0000017f0000000001",
      "branchEncodedKey": "8a8e8e8e7f0000017f0000000002",
      "clientEncodedKey": "CUST-BUS-456",
      "productEncodedKey": "PROD-BUSINESS-002"
    },
    "accountInformation": {
      "loanAmount": 750000.00,
      "interestRate": 12.5,
      "loanTenor": 60,
      "notes": "Equipment purchase and working capital",
      "firstRepaymentDate": "2024-05-15T00:00:00Z",
      "moratoriumType": 1,
      "moratoriumPeriod": 3
    },
    "disbursementInformation": {
      "disbursementDate": "2024-02-15T00:00:00Z",
      "disbursementMethod": "BankTransfer",
      "disbursmentChannelEncodedKey": "8a8e8e8e7f0000017f0000000003"
    },
    "comments": ["Priority commercial client", "Fast-track approval requested"],
    "tags": ["business", "equipment-financing", "working-capital"],
    "salesChannelCode": "CORPORATE"
  }
}

Error Codes

Code	Message	Description
LOAN_001	Customer not found	Customer ID does not exist
LOAN_002	Customer not eligible	Customer fails credit checks
LOAN_003	Invalid loan product	Loan product ID not found
LOAN_004	Amount exceeds limit	Loan amount above product maximum
LOAN_005	Invalid interest rate	Rate outside allowed range
LOAN_006	Invalid loan term	Term not within product limits
LOAN_007	Collateral required	Secured product requires collateral
LOAN_008	Insufficient collateral	Collateral value below requirements
LOAN_009	Invalid guarantor	Guarantor not found or ineligible
LOAN_010	Duplicate application	Active application already exists
LOAN_011	Invalid account	Disbursement/repayment account invalid
LOAN_012	Invalid officer	Loan officer not found or inactive

Integration Points

Related Endpoints

• POST /api/bpm/cmd with GetLoanAccountsCommand - Retrieve loan accounts
• POST /api/bpm/cmd with GetLoanAccountCommand - Get loan details
• POST /api/bpm/cmd with UpdateLoanCommand - Update loan information
• POST /api/bpm/cmd with ApproveLoanCommand - Approve loan application
• POST /api/bpm/cmd with GenerateLoanScheduleCommand - Generate repayment schedule

Webhooks

Loan creation triggers the following webhooks:

• loan.created - Fired when loan is successfully created
• loan.pending_approval - Fired when loan enters approval workflow
• workflow.approval_required - Fired when approval is required

Event Notifications

The system publishes these events:

• Email notification to customer about loan application
• SMS confirmation with application reference
• Alert to assigned loan officer
• Notification to approvers if approval required

Notes

• Loan accounts must be approved before disbursement
• Interest calculations depend on product configuration
• Repayment schedules are generated after approval
• Multiple collateral items can be linked post-creation
• Guarantor acceptance may be required
• Credit bureau checks may be performed automatically
• All monetary amounts should use appropriate decimal precision