Cancel Cheque

Cancel a pending cheque through user-initiated stop payment or internal cancellation.

Command: InitiateCancelChequeCommand

Overview

The Cancel Cheque operation stops a pending cheque transaction before it is cleared. This is typically used for stop payment requests from customers or internal corrections. For deposits, this reduces uncleared amounts. For withdrawals, this restores the previously deducted balance.

Cancel vs. Bounce

Cancel: User-initiated, proactive stop payment (customer request, error correction)
Bounce: Bank-initiated, reactive return (insufficient funds, account closed)

Request

{
  "clearingEncodedKey": "8a8087e27f2f63a2017f3b0c0c7b0005",
  "notes": "Customer stop payment - cheque lost"
}

Parameters

Parameter	Type	Required	Description
clearingEncodedKey	string	Yes	Cheque clearing transaction ID
notes	string	No	Cancellation reason and notes

Business Logic

1. Validation

Cheque clearing transaction must exist
Must be in PENDING state
Cannot cancel already CLEARED/BOUNCED/CANCELLED cheques

2. State Changes

State: PENDING → CANCELLED
Full reversal of all impacts:
- Deposits: Reduce UnclearedChequeAmount
- Withdrawals: Restore balance
Records cancellation reason and authorization
Customer notified of cancellation

Common Cancellation Reasons

Reason Code	Description	Authorization Required
CUSTOMER_REQUEST	Customer stop payment	Customer signature/ID
DUPLICATE_ENTRY	Duplicate transaction	Branch manager approval
LOST_CHEQUE	Lost or stolen cheque	Police report + customer ID
WRONG_AMOUNT	Incorrect amount entered	Branch manager approval
FRAUD_PREVENTION	Suspected fraud detected	Security officer approval
ACCOUNT_ERROR	Wrong account selected	Operations manager approval
SYSTEM_ERROR	System error/glitch	IT manager verification
COMPLIANCE_HOLD	Compliance hold/investigation	Compliance officer authorization

Response (200 OK)

{
  "encodedKey": "8a8087e27f2f63a2017f3b0c0c7b0005",
  "chequeNumber": "CHQ-123456",
  "accountNumber": "1001234567",
  "amount": 75000.00,
  "transactionType": "WITHDRAWAL",
  "state": "CANCELLED",
  "previousState": "PENDING",
  "cancelledDate": "2025-12-31T14:00:00Z",
  "cancellationNotes": "Customer stop payment - cheque lost",
  "restoredBalance": 1000000.00
}

Example: Stop Payment Request

// Customer requests stop payment on a cheque
const response = await fetch('https://api.banklingo.com/api/admin/teller/cheques/cancel', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    clearingEncodedKey: '8a8087e27f2f63a2017f3b0c0c7b0005',
    notes: 'Customer stop payment request - cheque book reported lost. Police report ref: NG-POLICE-2025-001234'
  })
});

if (response.ok) {
  const result = await response.json();
  console.log('Cheque cancelled successfully');
  console.log(`Cheque number: ${result.chequeNumber}`);
  console.log(`Amount: ₦${result.amount.toLocaleString()}`);
  
  if (result.transactionType === 'WITHDRAWAL') {
    console.log(`Balance restored: ₦${result.restoredBalance.toLocaleString()}`);
  }
  
  // Apply stop payment fee
  await applyStopPaymentFee(result.accountNumber, 1000); // ₦1,000 stop payment fee
  
  // Notify customer
  await notifyCustomer(result.accountNumber, {
    type: 'CHEQUE_CANCELLED',
    chequeNumber: result.chequeNumber,
    reason: result.cancellationNotes,
    feeApplied: 1000
  });
}

Example: Cancel Deposit (Error Correction)

// Cancel deposit due to duplicate entry
const response = await fetch('https://api.banklingo.com/api/admin/teller/cheques/cancel', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    clearingEncodedKey: '9b9087e27f2f63a2017f3b0c0c7b0006',
    notes: 'Duplicate entry - cheque already processed under ref: CHQ-DEP-2025-0001'
  })
});

if (response.ok) {
  const result = await response.json();
  console.log('Duplicate deposit cancelled');
  console.log(`Uncleared amount reduced by: ₦${result.amount.toLocaleString()}`);
}

Error Responses

400 Bad Request - Invalid State

{
  "code": "INVALID_CHEQUE_STATE",
  "message": "Cannot cancel cheque in state: CLEARED",
  "field": "clearingEncodedKey"
}

404 Not Found

{
  "code": "CHEQUE_CLEARING_NOT_FOUND",
  "message": "Cheque clearing transaction not found",
  "field": "clearingEncodedKey"
}

409 Conflict - Already Cancelled

{
  "code": "CHEQUE_ALREADY_CANCELLED",
  "message": "Cheque has already been cancelled",
  "field": "clearingEncodedKey"
}

Clear Cheque: Finalize successful clearing
Bounce Cheque: Bank-initiated dishonor
Get Uncleared Cheque: Query pending cheques
Get All Cheque Clearing Requests: List all clearing requests
Initiate Cheque Deposit: Create deposit that may be cancelled
Initiate Cheque Withdrawal: Create withdrawal that may be cancelled

Best Practices

Stop Payment Process

Verify customer identity thoroughly before processing stop payment
Collect supporting documentation:
- Customer signature on stop payment form
- ID verification
- Police report (for lost/stolen cheques)
Apply stop payment fee as per bank policy (typically ₦1,000-₦2,000)
Record authorization from appropriate officer
Issue stop payment reference to customer

Authorization Requirements

Different cancellation reasons require different authorization levels:

Cancellation Reason	Authorizer	Documentation Required
Customer stop payment	Customer signature	Stop payment form + ID
Lost/stolen cheque	Customer + Manager	Police report + affidavit
Duplicate entry	Branch Manager	Transaction audit report
Wrong amount	Operations Manager	Error correction form
Fraud prevention	Security Officer	Fraud alert report
System error	IT Manager	System error log

Timing Considerations

Process immediately for customer stop payments (don't wait for clearing)
Cancel before clearing completes (usually before T+2)
Cannot cancel after cheque has been cleared or bounced
Window closes once clearing house confirms transaction

Customer Communication

Confirm cancellation to customer immediately
Provide cancellation reference for records
Explain fee charges clearly
Inform of timeline (cancellation is immediate)
Advise on next steps (e.g., reissue cheque, use alternative payment method)

Fee Management

Standard fees for cancellation/stop payment:

Cancellation Type	Typical Fee	Waiver Conditions
Customer stop payment	₦1,000 - ₦2,000	Lost/stolen with police report
Duplicate entry (bank error)	Waived	Bank error - no customer charge
Fraud prevention	Waived	Fraud detected by bank
Account error (bank error)	Waived	Bank error - no customer charge
System error	Waived	System error - no customer charge

Audit Trail

Maintain comprehensive audit trail for all cancellations:

Record who initiated cancellation (customer, staff, system)
Record who authorized cancellation
Record why (cancellation reason code)
Record when (timestamp)
Attach documentation (scanned forms, police reports)
Track fees applied and collected
Retain records for minimum 7 years

Compliance

Follow CBN guidelines on stop payment procedures
Maintain stop payment register for regulatory reporting
Report suspicious patterns (e.g., excessive stop payments)
Verify blacklisted cheques before cancelling
Coordinate with fraud team for fraud-related cancellations

Overview​

Request​

Parameters​

Business Logic​

1. Validation​

2. State Changes​

Common Cancellation Reasons​

Response (200 OK)​

Example: Stop Payment Request​

Example: Cancel Deposit (Error Correction)​

Error Responses​

400 Bad Request - Invalid State​

404 Not Found​

409 Conflict - Already Cancelled​

Related Operations​

Best Practices​

Stop Payment Process​

Authorization Requirements​

Timing Considerations​

Customer Communication​

Fee Management​

Audit Trail​

Compliance​