CreateStatementCommand

Overview

The CreateStatementCommand allows you to manually record bank statement and salary history data for loan applications. This command is used when bank statements are obtained through offline channels or when automated statement fetching is not available.

Handler File: CB.Administration.Api/Commands/BPM/SelfService/SelfServiceserDetailCommandHandlers.cs

Use Cases

• Recording bank statements obtained physically from customers
• Manual entry of salary history from paper statements
• Importing historical statement data
• Supporting banks not integrated with automated statement fetching
• Recording statements from alternative income verification sources

Request Parameters

Required Parameters

Parameter	Type	Description
loanQuoteId	long	The ID of the loan quote/application
accountNumber	string	Bank account number
bankCode	string	Bank code/identifier

Optional Parameters

Parameter	Type	Default	Description
accountName	string	""	Name of the account holder
provider	string	"Manual Entry"	Source of the statement data
numberOfSalaries	int	0	Number of salary credits identified
averageSalary	decimal	0.00	Average salary amount
lastSalary	decimal	0.00	Most recent salary amount
additionalData	string	""	Additional JSON data or notes
bankId	long?	null	Internal bank identifier (if applicable)

Request Example

{
  "commandName": "CreateStatementCommand",
  "data": {
    "loanQuoteId": 999,
    "accountNumber": "1234567890",
    "bankCode": "044",
    "accountName": "John Doe",
    "provider": "Manual Entry",
    "numberOfSalaries": 12,
    "averageSalary": 250000.00,
    "lastSalary": 280000.00,
    "additionalData": "{\"months\": 12, \"currency\": \"NGN\", \"period\": \"2025-01 to 2025-12\"}",
    "bankId": 5
  }
}

Response Format

Success Response

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Bank statement record created successfully.",
  "data": {
    "statementId": 890,
    "loanQuoteId": 999,
    "accountNumber": "1234567890",
    "bankCode": "044",
    "accountName": "John Doe",
    "provider": "Manual Entry",
    "searchStatus": 1,
    "searchStatusDesc": "Successful",
    "searchDate": "2026-01-11T15:00:00Z",
    "numberOfSalaries": 12,
    "averageSalary": 250000.00,
    "lastSalary": 280000.00,
    "createdAt": "2026-01-11T15:00:00Z"
  }
}

Error Responses

Loan Quote Not Found

{
  "isSuccessful": false,
  "statusCode": "04",
  "message": "Loan quote not found."
}

Duplicate Statement

{
  "isSuccessful": false,
  "statusCode": "04",
  "message": "A statement record already exists for this account and loan quote."
}

Validation Rules

1. Loan Quote Existence: The loanQuoteId must reference an existing loan quote/application
2. No Duplicates: Cannot create multiple statement records for the same accountNumber, bankCode, and loanQuoteId combination
3. Required Fields: Account number and bank code must be provided

Search Status

Statement records created through this command are automatically marked as Successful (status = 1), indicating that the statement analysis was completed.

Available Status Values:

• 0 - Pending: Statement fetch initiated but not complete
• 1 - Successful: Statement obtained and analyzed
• 2 - Failed: Statement fetch failed

Salary Analysis Guidelines

Income Assessment

Metric	Calculation	Purpose
Average Salary	Sum of salaries / Number of months	Determine consistent income level
Last Salary	Most recent salary credit	Verify current income status
Number of Salaries	Count of salary credits in period	Assess employment stability

Loan Affordability Calculation

Maximum Monthly Repayment = Average Salary × 33%
(33% is typical debt-to-income ratio limit)

Example:
Average Salary: ₦250,000
Max Monthly Payment: ₦82,500
Max Loan (12 months @ 5%): ~₦920,000

Risk Assessment

Salary Pattern	Risk Level	Recommendation
Consistent monthly salaries	Low	Approve
Irregular but adequate	Medium	Review
Declining trend	High	Review/Decline
Insufficient income	High	Decline

Related Commands

• FetchStatementCommand - Automatically fetch statements via API integration (alternative to manual entry)
• GetCustomerLoanSalaryHistoryQuery - Retrieve statement records for a loan

Integration Example

cURL Request

curl -X POST https://api.banklingo.com/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "commandName": "CreateStatementCommand",
    "data": {
      "loanQuoteId": 999,
      "accountNumber": "1234567890",
      "bankCode": "044",
      "accountName": "John Doe",
      "numberOfSalaries": 12,
      "averageSalary": 250000.00,
      "lastSalary": 280000.00
    }
  }'

JavaScript Example

const response = await fetch('https://api.banklingo.com/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    commandName: 'CreateStatementCommand',
    data: {
      loanQuoteId: 999,
      accountNumber: '1234567890',
      bankCode: '044',
      accountName: 'John Doe',
      numberOfSalaries: 12,
      averageSalary: 250000.00,
      lastSalary: 280000.00,
      additionalData: JSON.stringify({
        months: 12,
        currency: 'NGN',
        period: '2025-01 to 2025-12'
      })
    }
  })
});

const result = await response.json();
console.log('Statement recorded:', result.data.statementId);

C# Example

var command = new
{
    CommandName = "CreateStatementCommand",
    Data = new
    {
        LoanQuoteId = 999,
        AccountNumber = "1234567890",
        BankCode = "044",
        AccountName = "John Doe",
        NumberOfSalaries = 12,
        AverageSalary = 250000.00m,
        LastSalary = 280000.00m,
        AdditionalData = JsonSerializer.Serialize(new {
            Months = 12,
            Currency = "NGN",
            Period = "2025-01 to 2025-12"
        })
    }
};

var result = await _mediator.Send(command);

Best Practices

1. Analysis Period: Analyze at least 6 months of statements (12 months preferred)
2. Salary Identification: Clearly identify salary credits vs other income
3. Documentation: Keep physical/digital copies of original statements
4. Accuracy: Double-check all calculated values before submission
5. Currency: Specify currency in additionalData for multi-currency systems
6. Privacy: Redact sensitive transaction details not needed for assessment
7. Verification: Cross-verify account ownership with ID documents

Common Nigerian Bank Codes

Bank	Code	Name
Access Bank	044	Access Bank Plc
GTBank	058	Guaranty Trust Bank
First Bank	011	First Bank of Nigeria
Zenith Bank	057	Zenith Bank Plc
UBA	033	United Bank for Africa
Ecobank	050	Ecobank Nigeria

Workflow Comparison

Automated vs Manual Statement Processing

Aspect	Automated (FetchStatementCommand)	Manual (CreateStatementCommand)
Integration	Direct API to banks	Manual data entry
Speed	Real-time (30-60 seconds)	Depends on operator
Accuracy	High (automated analysis)	Depends on data entry
Cost	Per-statement API fees	Staff time
Coverage	Integrated banks only	Any bank/source

Technical Notes

• Entity: SalaryHistorySearch
• Database Table: BPMLoanSelfService.SalaryHistorySearch
• Naming: Despite the name, this entity stores bank statement/salary history data
• Loan-Specific: Statement records are tied to specific loan applications via LoanQuoteId
• Duplicate Prevention: System prevents adding multiple statements for the same account and loan
• Status: Automatically set to "Successful" (1) when created

Additional Data Structure

The additionalData field accepts JSON for extended information:

{
  "months": 12,
  "currency": "NGN",
  "period": "2025-01 to 2025-12",
  "analysisMethod": "Manual",
  "analyst": "John Smith",
  "notes": "Consistent salary payments on last day of each month"
}

See Also

• Create Credit Bureau Search
• Create Guarantor
• Loan Approval Workflow
• Commands Overview