Initiate Cheque Deposit (Deposit Account)

Post a cheque deposit transaction to a deposit account in PENDING state.

Command: InitiateChequeDepositCommand

Overview

The Cheque Deposit command initiates a cheque deposit to a deposit account (savings, current, etc.). The transaction enters a PENDING state and increases the UnclearedChequeAmount, but does not credit the actual balance until the cheque is cleared using the InitiateClearChequeCommand.

Same Command, Different Behavior

This same command (InitiateChequeDepositCommand) can also be used to repay loan accounts. See Cheque Deposit to Loan Account for loan repayment documentation.

Key Characteristics

Balance: Unchanged until clearing
UnclearedChequeAmount: Increases immediately by deposit amount
State: Creates transaction in PENDING state
Clearing: Requires InitiateClearChequeCommand to credit balance
Timeline: Typical T+2 clearing period (configurable)

Request

Endpoint

POST /api/bpm/cmd

Request Body

{
  "commandName": "InitiateChequeDepositCommand",
  "data": {
    "accountEncodedKey": "1001234567",
    "amount": 50000.00,
    "chequeNo": "CH123456",
    "tillId": "TILL001",
    "referenceId": "REF2025123001",
    "requireApproval": false,
    "remarks": "Customer cheque deposit"
  }
}

Parameters

Parameter	Type	Required	Description
`accountEncodedKey`	string	Yes	Deposit account number or encoded key
`amount`	decimal	Yes	Deposit amount (must be > 0)
`chequeNo`	string	Yes	Unique cheque number
`tillId`	string	No	Till ID or encoded key for teller transactions
`referenceId`	string	No	External reference ID for tracking
`requireApproval`	boolean	No	Whether transaction requires approval before entering clearing cycle. Default: `false`
`remarks`	string	No	Additional transaction notes or comments

Business Logic

Validation Rules

Amount Validation:
- Must be greater than 0
- Must be within system-defined limits (if configured)
Account Validation:
- Account must exist in the system
- Account must not be frozen or locked
- Account must not be in a restricted state
Till Validation (if tillId provided):
- Till must be in OPENED state
- Till currency must match account currency
- Teller must have permission to use the till
Cheque Validation:
- Cheque number should be unique (duplicate check recommended)
- Cheque should not be in system as bounced/cancelled previously

State Changes

When command executes successfully:

Creates ChequeClearingTransaction record:
- State: PENDING
- Transaction Type: DEPOSIT
- Amount: As specified
- Cheque Number: As specified
Updates Deposit Account:
- Balance: Unchanged (awaiting clearing)
- UnclearedChequeAmount: Increased by deposit amount
- AvailableBalance: Unchanged (based on actual balance)
Records Transaction Impacts:
- Creates audit trail entries
- Links to till transaction (if applicable)
- Generates transaction reference
Approval Handling:
- If requireApproval: false (default): Transaction enters PENDING clearing immediately
- If requireApproval: true: Transaction enters APPROVAL_PENDING, awaits approval before entering clearing cycle

Response

Success Response (200 OK)

{
  "commandName": "InitiateChequeDepositCommand",
  "status": "Success",
  "data": {
    "chequeClearingId": "550e8400-e29b-41d4-a716-446655440000",
    "accountNumber": "1001234567",
    "amount": 50000.00,
    "chequeNo": "CH123456",
    "transactionType": "DEPOSIT",
    "state": "PENDING",
    "transactionDate": "2025-12-31T10:30:00Z",
    "unclearedChequeAmount": 50000.00,
    "currentBalance": 1000000.00
  }
}

Response Fields

Field	Type	Description
`chequeClearingId`	string (GUID)	Unique identifier for the cheque clearing transaction
`accountNumber`	string	Account number where cheque was deposited
`amount`	decimal	Deposit amount
`chequeNo`	string	Cheque number
`transactionType`	string	Always `DEPOSIT` for this command
`state`	string	Current state: `PENDING` or `APPROVAL_PENDING`
`transactionDate`	datetime	When transaction was initiated
`unclearedChequeAmount`	decimal	Current uncleared cheque amount on account
`currentBalance`	decimal	Current account balance (unchanged by deposit)

Account State Impact

The following diagram illustrates how cheque deposits affect account balances through a two-stage process:

Key Points

Stage 1 (Deposit): Transaction created in PENDING state, UnclearedChequeAmount increases, actual balance unchanged
Stage 2 (Clearing): Balance credited, UnclearedChequeAmount reduced, funds become available
Alternative (Bounce): UnclearedChequeAmount reduced, balance remains unchanged, cheque returned

Code Examples

Basic Deposit

const response = await fetch('https://api.banklingo.com/api/bpm/cmd', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    commandName: 'InitiateChequeDepositCommand',
    data: {
      accountEncodedKey: '1001234567',
      amount: 50000.00,
      chequeNo: 'CH123456',
      tillId: 'TILL001',
      remarks: 'Customer cheque deposit'
    }
  })
});

const result = await response.json();
console.log('Clearing ID:', result.data.chequeClearingId);
console.log('State:', result.data.state); // "PENDING"

Deposit with Approval Required

const response = await fetch('https://api.banklingo.com/api/bpm/cmd', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    commandName: 'InitiateChequeDepositCommand',
    data: {
      accountEncodedKey: '1001234567',
      amount: 750000.00, // High-value deposit
      chequeNo: 'CH789012',
      requireApproval: true, // Requires approval before entering clearing
      remarks: 'High-value third-party cheque'
    }
  })
});

const result = await response.json();
console.log('State:', result.data.state); // "APPROVAL_PENDING"
// Transaction will enter PENDING clearing only after approval

High-Value Deposit with External Reference

const response = await fetch('https://api.banklingo.com/api/bpm/cmd', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    commandName: 'InitiateChequeDepositCommand',
    data: {
      accountEncodedKey: '1001234567',
      amount: 2500000.00,
      chequeNo: 'CH345678',
      referenceId: 'NIBSS202512310001',
      tillId: 'TILL001',
      requireApproval: true,
      remarks: 'Inter-bank clearing - NIBSS reference'
    }
  })
});

Error Responses

Common Errors

Status Code	Error	Description	Resolution
400	`INVALID_AMOUNT`	Amount is zero or negative	Provide amount > 0
404	`ACCOUNT_NOT_FOUND`	Account doesn't exist	Verify account number
403	`ACCOUNT_FROZEN`	Account is frozen/locked	Contact account services
403	`TILL_NOT_OPENED`	Till is not in OPENED state	Open till before processing
400	`CURRENCY_MISMATCH`	Till currency doesn't match account currency	Use correct till for currency
409	`DUPLICATE_CHEQUE`	Cheque number already exists	Use unique cheque number

Error Response Format

{
  "commandName": "InitiateChequeDepositCommand",
  "status": "Error",
  "message": "Transaction not permitted. The customer account - 1001234567 is on restriction.",
  "statusCode": "06"
}

Approval Workflow Integration

Without Approval (Default Behavior)

With Approval Required

Next Steps

After initiating a cheque deposit:

Track Transaction: Use the returned chequeClearingId to monitor status
Clear Cheque: When ready, use InitiateClearChequeCommand to credit the balance
Bounce If Needed: If cheque is dishonored, use InitiateBounceChequeCommand
Monitor Uncleared Amount: Track total uncleared amounts for liquidity management

Clear Cheque: Finalize cheque deposit and credit balance
Bounce Cheque: Return dishonored cheque
Cancel Cheque: Stop payment on pending cheque
Get Uncleared Cheque: Retrieve uncleared cheque details

Best Practices

Security

Validate cheque numbers against duplicates before initiating
Implement approval workflow for high-value deposits (> ₦500,000)
Verify third-party cheques with additional scrutiny
Log all cheque transactions for audit trail

Performance

Batch clear cheques during off-peak hours
Monitor clearing timelines and alert on delays
Index cheque numbers for fast duplicate detection
Cache account information to reduce database hits

Customer Experience

Provide immediate confirmation with clearing timeline
Send notifications when cheques are cleared or bounced
Display uncleared amounts prominently in account views
Offer real-time clearing status updates

Product Documentation

For business process and technical flow details, see:

Overview​

Key Characteristics​

Request​

Endpoint​

Request Body​

Parameters​

Business Logic​

Validation Rules​

State Changes​

Response​

Success Response (200 OK)​

Response Fields​

Account State Impact​

Key Points​

Code Examples​

Basic Deposit​

Deposit with Approval Required​

High-Value Deposit with External Reference​

Error Responses​

Common Errors​

Error Response Format​

Approval Workflow Integration​

Without Approval (Default Behavior)​

With Approval Required​

Next Steps​

Related Commands​

Best Practices​

Security​

Performance​

Customer Experience​

Product Documentation​