Initiate Cheque Withdrawal

Issue a cheque (withdrawal) from a deposit account with immediate balance deduction.

Command: InitiateChequeWithdrawalCommand

Overview

The Cheque Withdrawal command issues a cheque from a deposit account. Unlike deposits, the withdrawal amount is immediately deducted from the account balance to prevent overdrawing. The transaction enters a PENDING state until the cheque is cleared or bounced.

Immediate Balance Deduction

Cheque withdrawals debit the account balance immediately upon initiation. This is a critical difference from cheque deposits, which only affect the balance after clearing.

Key Characteristics

• Balance: Immediately deducted (not waiting for clearing)
• State: Creates transaction in PENDING state
• Clearing: Normal clearing process confirms withdrawal
• Bounce: Can restore funds if cheque is dishonored
• Purpose: Risk mitigation to prevent overdrafts

Request

Endpoint

POST /api/bpm/cmd

Request Body

{
  "commandName": "InitiateChequeWithdrawalCommand",
  "data": {
    "accountEncodedKey": "1001234567",
    "amount": 75000.00,
    "chequeNo": "CH789012",
    "payeeName": "ABC Suppliers Ltd",
    "tillId": "TILL001",
    "referenceId": "REF2025123002",
    "requireApproval": false,
    "remarks": "Payment to supplier"
  }
}

Parameters

Parameter	Type	Required	Description
accountEncodedKey	string	Yes	Deposit account number or encoded key
amount	decimal	Yes	Withdrawal amount (must be > 0)
chequeNo	string	Yes	Unique cheque number
payeeName	string	No	Name of the payee/beneficiary
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 withdrawal. Default: false
remarks	string	No	Additional transaction notes or comments

Business Logic

Validation Rules

1. Amount Validation:

   • Must be greater than 0
   • Account must have sufficient balance (withdrawal amount ≤ available balance)

2. Account Validation:

   • Account must exist in the system
   • Account must not be frozen or locked
   • Account must have sufficient funds

3. Till Validation (if tillId provided):

   • Till must be in OPENED state
   • Till currency must match account currency

4. Cheque Validation:

   • Cheque number should be unique
   • Cheque should not be previously issued/bounced

State Changes

When command executes successfully:

1. Creates ChequeClearingTransaction record:

   • State: PENDING
   • Transaction Type: WITHDRAWAL
   • Amount: As specified
   • Payee Name: As specified

2. Updates Deposit Account:

   • Balance: Immediately reduced by withdrawal amount
   • AvailableBalance: Immediately reduced
   • Cheque issued and can be presented for clearing

3. If Cleared (normal flow):

   • Transaction moves to SETTLED state
   • Balance remains deducted (withdrawal confirmed)

4. If Bounced (dishonored):

   • Transaction moves to BOUNCED state
   • Balance restored (funds returned to account)
   • Bounce fees may apply (configurable)

5. Approval Handling:

   • If requireApproval: false (default): Balance debited immediately, transaction enters PENDING
   • If requireApproval: true: Hold placed, balance not debited until approved

Response

Success Response (200 OK)

{
  "commandName": "InitiateChequeWithdrawalCommand",
  "status": "Success",
  "data": {
    "chequeClearingId": "660e8400-e29b-41d4-a716-446655440000",
    "accountNumber": "1001234567",
    "amount": 75000.00,
    "chequeNo": "CH789012",
    "transactionType": "WITHDRAWAL",
    "state": "PENDING",
    "payeeName": "ABC Suppliers Ltd",
    "transactionDate": "2025-12-31T11:00:00Z",
    "currentBalance": 925000.00
  }
}

Response Fields

Field	Type	Description
chequeClearingId	string (GUID)	Unique identifier for the cheque clearing transaction
accountNumber	string	Account number from which cheque was issued
amount	decimal	Withdrawal amount
chequeNo	string	Cheque number
transactionType	string	Always WITHDRAWAL for this command
state	string	Current state: PENDING or APPROVAL_PENDING
payeeName	string	Name of the payee/beneficiary
transactionDate	datetime	When transaction was initiated
currentBalance	decimal	Current account balance (already reduced by withdrawal)

Account State Impact

The following diagram illustrates how cheque withdrawals affect account balances and the possible outcomes:

Key Points

• Immediate Deduction: Withdrawal amount deducted from balance immediately (not waiting for clearing)
• Cleared Path: Transaction moves to SETTLED state, balance remains deducted
• Bounced Path: Transaction reversed, funds restored to account (minus bounce fees if applicable)
• Risk Mitigation: Immediate deduction prevents overdraft scenarios

Code Examples

Basic Withdrawal

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: 'InitiateChequeWithdrawalCommand',
    data: {
      accountEncodedKey: '1001234567',
      amount: 75000.00,
      chequeNo: 'CH789012',
      payeeName: 'ABC Suppliers Ltd',
      remarks: 'Payment to supplier'
    }
  })
});

const result = await response.json();
console.log('Clearing ID:', result.data.chequeClearingId);
console.log('New Balance:', result.data.currentBalance); // Balance already deducted

High-Value Withdrawal with Approval

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: 'InitiateChequeWithdrawalCommand',
    data: {
      accountEncodedKey: '1001234567',
      amount: 1500000.00, // High-value withdrawal
      chequeNo: 'CH456789',
      payeeName: 'Major Vendor Ltd',
      requireApproval: true, // Requires approval before debiting
      remarks: 'Large payment - requires authorization'
    }
  })
});

const result = await response.json();
console.log('State:', result.data.state); // "APPROVAL_PENDING"
console.log('Balance:', result.data.currentBalance); // Balance NOT YET deducted
// After approval, balance will be debited

Withdrawal 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: 'InitiateChequeWithdrawalCommand',
    data: {
      accountEncodedKey: '1001234567',
      amount: 250000.00,
      chequeNo: 'CH111222',
      payeeName: 'Government Tax Authority',
      referenceId: 'TAX-2025-Q1-001',
      tillId: 'TILL001',
      remarks: 'Quarterly tax payment'
    }
  })
});

Error Responses

Common Errors

Status Code	Error	Description	Resolution
400	INVALID_AMOUNT	Amount is zero or negative	Provide amount > 0
400	INSUFFICIENT_FUNDS	Account balance insufficient	Check available balance
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
409	DUPLICATE_CHEQUE	Cheque number already exists	Use unique cheque number

Error Response Format

{
  "commandName": "InitiateChequeWithdrawalCommand",
  "status": "Error",
  "message": "Insufficient funds. Available balance: ₦50,000.00, Withdrawal amount: ₦75,000.00",
  "statusCode": "51"
}

Approval Workflow Integration

Without Approval (Default Behavior)

With Approval Required

Bounce vs. Clear Scenarios

Normal Clearing (Cheque Honored)

1. Withdrawal Initiated: Balance debited ₦75,000
2. Cheque Presented: Payee presents cheque to their bank
3. Clearing Process: Inter-bank clearing (T+2 typically)
4. Cleared: Transaction moves to SETTLED, balance remains deducted

Bounce Scenario (Cheque Dishonored)

1. Withdrawal Initiated: Balance debited ₦75,000
2. Cheque Presented: Payee presents cheque to their bank
3. Bounce Initiated: Use InitiateBounceChequeCommand
4. Bounced: Transaction moves to BOUNCED, balance restored ₦75,000

Common Bounce Reasons:

• Signature mismatch
• Post-dated cheque presented early
• Stop payment request by customer
• Account closed after cheque issuance
• Cheque defaced or damaged

Next Steps

After initiating a cheque withdrawal:

1. Track Transaction: Use the returned chequeClearingId to monitor status
2. Monitor Clearing: Track when payee presents cheque for clearing
3. Handle Bounce: If dishonored, use InitiateBounceChequeCommand to restore funds
4. Confirm Clearing: Normal clearing finalizes withdrawal (no additional action needed)

Related Commands

• Initiate Cheque Deposit: Deposit cheque to account (opposite operation)
• Bounce Cheque: Return dishonored cheque and restore funds
• Cancel Cheque: Stop payment on pending cheque
• Get Uncleared Cheque: Retrieve pending cheque details

Best Practices

Security

• Validate payee information before issuing cheques
• Implement approval workflow for high-value withdrawals (> ₦1,000,000)
• Verify customer identity for large cheque issuances
• Log all cheque withdrawals for audit trail
• Monitor for duplicate cheque numbers

Balance Management

• Check available balance before processing withdrawal
• Reserve funds immediately to prevent overdrafts
• Track pending withdrawals for liquidity planning
• Alert customers when large withdrawals occur
• Provide real-time balance updates after withdrawal

Customer Experience

• Provide immediate confirmation with current balance
• Display pending cheques in account statements
• Send notifications when cheques are cleared or bounced
• Offer stop payment functionality for issued cheques
• Show cheque status in real-time via customer portal

Operational

• Batch process clearing confirmations during off-peak hours
• Monitor bounce rates and investigate patterns
• Track average clearing times by bank/region
• Maintain cheque register for reconciliation
• Generate alerts for unusual withdrawal patterns

---

Product Documentation

For business process and technical flow details, see:

• Cheque Transactions - Technical Flow
• Cheque Transactions Overview