Clear Cheque

Clear (finalize) a pending cheque transaction to credit deposits or settle withdrawals.

Command: InitiateClearChequeCommand

Overview

The Clear Cheque operation finalizes a cheque transaction after the clearing period has elapsed or been confirmed by the clearing house. For deposits, this credits the account balance and reduces uncleared amounts. For withdrawals, this marks the transaction as settled (balance was already deducted).

Clearing Timeline

Most local inter-bank cheques follow a T+2 clearing cycle through NIBSS (Nigerian Inter-Bank Settlement System).

Request

{
  "clearingEncodedKey": "8a8087e27f2f63a2017f3b0c0c7b0005",
  "externalReferenceId": "NIBSS202512310001",
  "notes": "T+2 clearing completed"
}

Parameters

Parameter	Type	Required	Description
clearingEncodedKey	string	Yes	Cheque clearing transaction ID
externalReferenceId	string	Yes	Clearing house reference number
notes	string	No	Clearing notes or remarks

Business Logic

1. Validation

• Cheque clearing transaction must exist
• Must be in PENDING state
• Cannot clear already CLEARED/BOUNCED/CANCELLED cheques
• External reference ID is mandatory

2. State Changes for DEPOSITS

• State: PENDING → CLEARED
• Credits account balance by deposit amount
• Reduces UnclearedChequeAmount by deposit amount
• Records clearing reference and timestamp

3. State Changes for WITHDRAWALS

• State: PENDING → SETTLED
• Balance already deducted (no change)
• Marks withdrawal as finalized
• Records clearing confirmation

Response (200 OK)

{
  "encodedKey": "8a8087e27f2f63a2017f3b0c0c7b0005",
  "chequeNumber": "CHQ-123456",
  "accountNumber": "1001234567",
  "amount": 50000.00,
  "transactionType": "DEPOSIT",
  "state": "CLEARED",
  "previousState": "PENDING",
  "clearedDate": "2025-12-31T15:00:00Z",
  "clearingReference": "NIBSS202512310001",
  "newBalance": 1050000.00,
  "newUnclearedAmount": 0.00
}

Clearing Timeline Example

Day	Event	State	Balance	UnclearedAmount
T+0	Deposit received	PENDING	₦1,000,000	₦50,000
T+1	Clearing house processing	PENDING	₦1,000,000	₦50,000
T+2	Clearing confirmed	CLEARED	₦1,050,000	₦0

Example: Clear Deposit Cheque

const response = await fetch('https://api.banklingo.com/api/admin/teller/cheques/clear', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    clearingEncodedKey: '8a8087e27f2f63a2017f3b0c0c7b0005',
    externalReferenceId: 'NIBSS202512310001',
    notes: 'T+2 clearing cycle completed successfully'
  })
});

if (response.ok) {
  const result = await response.json();
  console.log('Cheque cleared successfully');
  console.log(`New balance: ₦${result.newBalance.toLocaleString()}`);
  console.log(`Uncleared amount: ₦${result.newUnclearedAmount.toLocaleString()}`);
}

Error Responses

400 Bad Request - Invalid State

{
  "code": "INVALID_CHEQUE_STATE",
  "message": "Cannot clear cheque in state: BOUNCED",
  "field": "clearingEncodedKey"
}

404 Not Found

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

409 Conflict - Already Cleared

{
  "code": "CHEQUE_ALREADY_CLEARED",
  "message": "Cheque has already been cleared",
  "field": "clearingEncodedKey"
}

Related Operations

• Get Uncleared Cheque: Query pending cheques awaiting clearing
• Get All Cheque Clearing Requests: List all clearing requests
• Bounce Cheque: Return dishonored cheque
• Cancel Cheque: Stop payment on pending cheque
• Initiate Cheque Deposit: Create deposit requiring clearing

Best Practices

Timing

1. Wait for clearing confirmation from clearing house (NIBSS, etc.)
2. Don't clear before T+2 for inter-bank cheques
3. Same-day clearing only for intra-bank or instant clearing agreements
4. Monitor clearing timelines and alert on delays beyond T+3

Reconciliation

1. Match clearing references with clearing house reports
2. Verify amounts match original deposit/withdrawal
3. Batch process clearings during off-peak hours for performance
4. Log all clearing operations for audit trail

Customer Communication

1. Notify customers when deposits are cleared and available
2. Send SMS/email alerts for balance updates
3. Update mobile/online banking displays immediately
4. Provide clearing reference for customer records