Cheque Transactions

Process cheque deposits, withdrawals, clearing, bouncing, and cancellations.

Overview

The Cheque Transactions API provides comprehensive cheque processing capabilities including:

Deposit: Post cheque deposits in PENDING state
Withdrawal: Issue cheques with immediate balance deduction
Clearing: Clear pending cheques (finalize transactions)
Bouncing: Return dishonored cheques
Cancellation: User-initiated stop payments

All commands are part of the BPMCore V2 architecture with complete business logic implementations.

Commands Summary

Command	Purpose	State Changes
`InitiateChequeDepositCommand`	Post cheque deposit	Creates PENDING, increases UnclearedAmount
`InitiateChequeWithdrawalCommand`	Issue cheque	Creates PENDING, immediate balance deduction
`InitiateClearChequeCommand`	Clear pending cheque	PENDING â†’ CLEARED/SETTLED, credits balance (deposits)
`InitiateBounceChequeCommand`	Bounce dishonored cheque	PENDING â†’ BOUNCED, restores balance (withdrawals)
`InitiateCancelChequeCommand`	Cancel cheque (stop payment)	PENDING â†’ CANCELLED, full reversal

Cheque Processing Workflow

Key Behaviors

Asymmetric Processing

Cheque Deposits (wait for clearing):

âœ… UnclearedAmount increases immediately
âŒ Balance unchanged until clearing
ðŸ“… Typical T+2 clearing period

Cheque Withdrawals (immediate deduction):

âœ… Balance deducted immediately
âœ… Prevents overdrawing
ðŸ’¡ Risk mitigation strategy

Approval Workflow

Overview

Cheque transactions in BankLingo support approval workflow in addition to the standard PENDING clearing state. This provides an additional layer of control before cheques enter the standard clearing cycle.

Two-Level State Management:

Transaction-Level State: Controls whether cheque transaction requires approval before entering clearing cycle
- requireApproval: false (default) â†’ Transaction enters PENDING clearing immediately
- requireApproval: true â†’ Transaction awaits approval before entering PENDING clearing
Cheque-Level Clearing State: Standard clearing lifecycle (PENDING â†’ CLEARED/BOUNCED/CANCELLED)
- Managed via clearing commands (Clear, Bounce, Cancel)
- Independent of transaction approval state

Transaction Approval States

Direct Clearing Entry (No Approval Required)

When requireApproval is false or omitted (default):

Cheque Deposits:

âœ… Transaction enters PENDING clearing immediately
âœ… UnclearedChequeAmount increases immediately
âœ… Balance unchanged (awaiting clearing via InitiateClearCheque)
âœ… Standard T+2 clearing period applies

Cheque Withdrawals:

âœ… Transaction enters PENDING clearing immediately
âœ… Balance debited immediately (withdrawal issued)
âœ… Cheque can be presented for clearing
âœ… Can be bounced or cancelled if needed

Approval Required Before Clearing

When requireApproval is true:

Cheque Deposits:

â³ Transaction enters APPROVAL_PENDING state
â³ UnclearedChequeAmount NOT increased (awaiting approval)
â³ Balance unchanged
â³ Does NOT enter clearing cycle until approved
â³ After approval â†’ Enters PENDING clearing state
â³ After approval â†’ UnclearedChequeAmount increases
â³ Then follows standard clearing workflow

Cheque Withdrawals:

â³ Transaction enters APPROVAL_PENDING state
â³ Balance NOT debited (awaiting approval)
â³ Hold placed to reserve funds (HoldAmount increased)
â³ Cheque NOT issued until approved
â³ After approval â†’ Balance debited, cheque issued
â³ After approval â†’ Enters PENDING clearing state

State Transition with Approval Workflow

Universal Transaction Management Commands

Cheque transactions support the same universal commands as all other transaction types:

1. Approve Transaction (APPROVAL_PENDING â†’ PENDING Clearing)

Command: ApproveTransactionCommand

Purpose: Approves a cheque transaction and moves it into clearing cycle

Request:

{
  "commandName": "ApproveTransactionCommand",
  "data": {
    "transactionKey": "CHQ123456",
    "approverNotes": "Cheque verified. Approved for clearing."
  }
}

Effect on Cheque Deposits:

âœ… Transaction state: APPROVAL_PENDING â†’ PENDING (Clearing)
âœ… UnclearedChequeAmount increased by deposit amount
âœ… Cheque enters clearing cycle
âœ… Balance still unchanged (awaits clearing command)
âœ… Can now use InitiateClearCheque after clearing period

Effect on Cheque Withdrawals:

âœ… Transaction state: APPROVAL_PENDING â†’ PENDING (Clearing)
âœ… Hold released (HoldAmount decreased)
âœ… Balance debited (withdrawal amount)
âœ… Cheque issued and can be presented
âœ… Can be bounced or cancelled if dishonored

2. Reject Transaction (APPROVAL_PENDING â†’ CANCELLED)

Command: RejectTransactionCommand

Purpose: Rejects a cheque transaction before entering clearing cycle

Request:

{
  "commandName": "RejectTransactionCommand",
  "data": {
    "transactionKey": "CHQ123456",
    "rejectionReason": "Cheque signature does not match specimen. Rejected."
  }
}

Effect:

âŒ Transaction state: APPROVAL_PENDING â†’ CANCELLED
âŒ Deposits: UnclearedChequeAmount unchanged (never entered clearing)
âŒ Withdrawals: Hold released, balance unchanged
âŒ Cheque transaction voided
âŒ Does NOT enter clearing cycle

3. Cancel Transaction (APPROVAL_PENDING â†’ CANCELLED)

Command: CancelTransactionCommand

Purpose: Cancels a cheque transaction before approval

Request:

{
  "commandName": "CancelTransactionCommand",
  "data": {
    "transactionKey": "CHQ123456",
    "cancellationReason": "Customer request - duplicate cheque submitted"
  }
}

Effect:

âŒ Same as Reject Transaction
âŒ Transaction cancelled before entering clearing
âŒ No impact on clearing cycle

4. Reverse Transaction (After CLEARED/BOUNCED/CANCELLED)

Command: ReverseTransactionCommand

Purpose: Reverses a fully completed cheque transaction

Request:

{
  "commandName": "ReverseTransactionCommand",
  "data": {
    "transactionKey": "CHQ123456",
    "reversalReason": "Cheque was cleared to wrong account. Reversing transaction."
  }
}

Effect:

âª Reverses completed cheque transaction
âª Uses TransactionImpactRecord for intelligent reversal
âª Deposits: Balance debited (reverses clearing credit)
âª Withdrawals: Balance credited (reverses withdrawal debit)
âª Complete audit trail maintained

Note: Use cheque-specific clearing commands (Clear, Bounce, Cancel) for PENDING cheques. Use Reverse for already CLEARED transactions.

Approval Workflow Use Cases

When to Use `requireApproval = true`

Cheque Deposits:

High-Value Cheques
- Cheques exceeding approval threshold (e.g., > â‚¦500,000)
- Third-party cheques requiring verification
- Foreign cheques requiring special clearing
Risk Management
- Suspicious cheque patterns
- First-time large cheques from new customers
- Cheques from high-risk payers
- Post-dated cheques requiring manager approval
Compliance
- Cheques requiring dual authorization
- AML flagged cheques
- Cheques requiring special documentation

Cheque Withdrawals:

High-Value Withdrawals
- Large cheque issuance (e.g., > â‚¦1,000,000)
- Cashier's cheques requiring authorization
- Manager's cheques
Operational Controls
- Dormant account cheque withdrawals
- Third-party cheque issuance
- Emergency or irregular cheque withdrawals
Fraud Prevention
- Unusual withdrawal patterns
- Cheques issued outside normal business hours
- High-risk account cheque withdrawals

When to Use `requireApproval = false` (Direct Clearing)

Standard Operations:

Routine cheque deposits within limits
Regular cheque withdrawals by account holders
Established customer transactions
Low-risk, low-value cheques

Configuration Recommendations

Approval Thresholds for Cheque Transactions:

Transaction Type	Direct Clearing	Approval Required
Cheque Deposit	â‰¤ â‚¦500,000	> â‚¦500,000
Cheque Withdrawal	â‰¤ â‚¦1,000,000	> â‚¦1,000,000
Third-Party Cheque	Never	Always
Post-Dated Cheque	Never	Always
Foreign Cheque	Never	Always
Dormant Account	Never	Always

Relationship Between Approval and Clearing

Important: The approval workflow (requireApproval) is separate from the clearing workflow:

Approval Level (Transaction Control):
- Controls entry into clearing cycle
- Uses universal commands (Approve, Reject, Cancel, Reverse)
- Optional additional control layer
Clearing Level (Cheque-Specific):
- Manages cheque lifecycle (PENDING â†’ CLEARED/BOUNCED/CANCELLED)
- Uses cheque-specific commands (Clear, Bounce, Cancel)
- Always required for cheque processing

Example Flow:

Cheque Deposit with Approval:
1. Submit InitiateChequeDeposit (requireApproval: true)
   â†’ State: APPROVAL_PENDING
   â†’ UnclearedAmount: No change

2. Approve Transaction (ApproveTransactionCommand)
   â†’ State: PENDING (enters clearing)
   â†’ UnclearedAmount: Increased

3. Clear Cheque (InitiateClearCheque) [after T+2]
   â†’ State: CLEARED
   â†’ Balance: Credited
   â†’ UnclearedAmount: Decreased

1. Cheque Deposit

Post a cheque deposit transaction in PENDING state.

Request

POST /api/bpm/cmd

{
  "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	Account number or encoded key
amount	decimal	Yes	Deposit amount (must be > 0)
chequeNo	string	Yes	Cheque number
tillId	string	No	Till ID or encoded key
referenceId	string	No	External reference
requireApproval	boolean	No	Whether transaction requires approval before clearing. Default: false
remarks	string	No	Transaction notes

Business Logic

Validation:
- Amount must be > 0
- Account must exist and not be frozen/locked
- Till must be OPENED (if provided)
- Till currency must match account currency
State Changes:
- Creates ChequeClearingTransaction in PENDING state
- Increases UnclearedChequeAmount by deposit amount
- Balance unchanged (waiting for clearing)
- Records transaction impacts for audit
Transaction Type: DEPOSIT

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
  }
}

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

Example: 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'
    }
  })
});

2. Cheque Withdrawal

Issue a cheque (withdrawal) with immediate balance deduction.

Request

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

Parameters

Parameter	Type	Required	Description
accountEncodedKey	string	Yes	Account number or encoded key
amount	decimal	Yes	Withdrawal amount (must be > 0)
chequeNo	string	Yes	Cheque number
payeeName	string	No	Name of the payee
tillId	string	No	Till ID or encoded key
referenceId	string	No	External reference
requireApproval	boolean	No	Whether transaction requires approval before clearing. Default: false
remarks	string	No	Transaction notes
tillId	string	No	Till ID or encoded key
payeeName	string	No	Payee/beneficiary name
referenceId	string	No	External reference
remarks	string	No	Transaction notes

Business Logic

Validation:
- Amount must be > 0
- Account must have sufficient balance
- Account must not be frozen/locked
- Till must be OPENED (if provided)
State Changes:
- Creates ChequeClearingTransaction in PENDING state
- Deducts balance IMMEDIATELY (not waiting for clearing)
- Transaction type: WITHDRAWAL
- Records payee name for tracking
Critical Difference: Unlike deposits, withdrawals affect balance immediately to prevent overdrawing.

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
  }
}

Account State Impact

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

Key Points:

Immediate Deduction: Unlike deposits, withdrawal amount is deducted immediately from balance
Cleared Path: Transaction moves to SETTLED state, balance remains deducted
Bounced Path: Transaction reversed, funds restored to account

Example: Issue Cheque

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'
    }
  })
});

3. Clear Cheque

Clear a pending cheque (finalize transaction).

Request

{
  "commandName": "InitiateClearChequeCommand",
  "data": {
    "chequeClearingId": "550e8400-e29b-41d4-a716-446655440000",
    "clearingReference": "NIBSS202512310001",
    "remarks": "T+2 clearing completed"
  }
}

Parameters

Parameter	Type	Required	Description
chequeClearingId	string	Yes	Cheque clearing transaction ID (GUID)
clearingReference	string	No	Clearing house reference
remarks	string	No	Clearing notes

Business Logic

Validation:
- Cheque clearing transaction must exist
- Must be in PENDING state
- Cannot clear already CLEARED/BOUNCED/CANCELLED cheques
State Changes for DEPOSITS:
- State: PENDING â†’ CLEARED
- Credits account balance by deposit amount
- Reduces UnclearedChequeAmount by deposit amount
- Records clearing reference and timestamp
State Changes for WITHDRAWALS:
- State: PENDING â†’ SETTLED
- Balance already deducted (no change)
- Marks withdrawal as finalized

Response (200 OK)

{
  "commandName": "InitiateClearChequeCommand",
  "status": "Success",
  "data": {
    "chequeClearingId": "550e8400-e29b-41d4-a716-446655440000",
    "previousState": "PENDING",
    "newState": "CLEARED",
    "accountNumber": "1001234567",
    "amount": 50000.00,
    "transactionType": "DEPOSIT",
    "clearedDate": "2025-12-31T15:00:00Z",
    "clearingReference": "NIBSS202512310001",
    "newBalance": 1050000.00,
    "newUnclearedAmount": 0.00
  }
}

Clearing Timeline

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

// After receiving clearing confirmation from NIBSS/clearing house
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: 'InitiateClearChequeCommand',
    data: {
      chequeClearingId: '550e8400-e29b-41d4-a716-446655440000',
      clearingReference: 'NIBSS202512310001',
      remarks: 'T+2 clearing completed'
    }
  })
});

4. Bounce Cheque

Bounce (dishonor) a pending cheque.

Request

{
  "commandName": "InitiateBounceChequeCommand",
  "data": {
    "chequeClearingId": "550e8400-e29b-41d4-a716-446655440000",
    "bounceReason": "INSUFFICIENT_FUNDS",
    "bounceReference": "NIBSS202512310002",
    "remarks": "Returned - insufficient funds"
  }
}

Parameters

Parameter	Type	Required	Description
chequeClearingId	string	Yes	Cheque clearing transaction ID (GUID)
bounceReason	string	Yes	Reason code (see table below)
bounceReference	string	No	Clearing house return reference
remarks	string	No	Bounce notes

Bounce Reasons

Code	Description	Common Scenario
INSUFFICIENT_FUNDS	Insufficient funds	Most common reason
ACCOUNT_CLOSED	Account closed	Account no longer active
SIGNATURE_MISMATCH	Signature mismatch	Signature doesn't match records
POST_DATED	Post-dated cheque	Presented before date
STALE_CHEQUE	Stale cheque	Older than 6 months
STOPPED_BY_DRAWER	Stopped by drawer	Customer stop payment
REFER_TO_DRAWER	Refer to drawer	Contact account holder
EFFECTS_NOT_CLEARED	Effects not cleared	Prior cheque not cleared

Business Logic

Validation:
- Cheque clearing transaction must exist
- Must be in PENDING state
- Cannot bounce already CLEARED/BOUNCED/CANCELLED cheques
- Bounce reason is mandatory
State Changes for DEPOSITS:
- State: PENDING â†’ BOUNCED
- Reduces UnclearedChequeAmount by deposit amount
- Balance remains unchanged (was never credited)
- Records bounce reason and reference
State Changes for WITHDRAWALS:
- State: PENDING â†’ CANCELLED
- Restores account balance by withdrawal amount
- Records bounce reason and reference
- Customer notified of returned cheque

Response (200 OK)

{
  "commandName": "InitiateBounceChequeCommand",
  "status": "Success",
  "data": {
    "chequeClearingId": "550e8400-e29b-41d4-a716-446655440000",
    "previousState": "PENDING",
    "newState": "BOUNCED",
    "accountNumber": "1001234567",
    "amount": 50000.00,
    "transactionType": "DEPOSIT",
    "bounceReason": "INSUFFICIENT_FUNDS",
    "bounceReference": "NIBSS202512310002",
    "bouncedDate": "2025-12-31T16:00:00Z",
    "newBalance": 1000000.00,
    "newUnclearedAmount": 0.00
  }
}

Example: Bounce 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: 'InitiateBounceChequeCommand',
    data: {
      chequeClearingId: '550e8400-e29b-41d4-a716-446655440000',
      bounceReason: 'INSUFFICIENT_FUNDS',
      bounceReference: 'NIBSS202512310002',
      remarks: 'Returned by paying bank - insufficient funds'
    }
  })
});

5. Cancel Cheque

Cancel a pending cheque (user-initiated stop payment).

Request

{
  "commandName": "InitiateCancelChequeCommand",
  "data": {
    "chequeClearingId": "550e8400-e29b-41d4-a716-446655440000",
    "cancellationReason": "CUSTOMER_REQUEST",
    "remarks": "Stop payment requested by customer"
  }
}

Parameters

Parameter	Type	Required	Description
chequeClearingId	string	Yes	Cheque clearing transaction ID (GUID)
cancellationReason	string	Yes	Cancellation reason code
remarks	string	No	Cancellation notes

Cancellation Reasons

Code	Description	Authorization Required
CUSTOMER_REQUEST	Customer stop payment	Yes (customer signature)
DUPLICATE_ENTRY	Duplicate transaction	Yes (branch manager)
LOST_CHEQUE	Lost/stolen cheque	Yes (police report)
WRONG_AMOUNT	Incorrect amount	Yes (branch manager)
FRAUD_PREVENTION	Suspected fraud	Yes (security officer)
ACCOUNT_ERROR	Account error	Yes (operations manager)
SYSTEM_ERROR	System error	Yes (IT manager)
COMPLIANCE_HOLD	Compliance hold	Yes (compliance officer)

Business Logic

Validation:
- Cheque clearing transaction must exist
- Must be in PENDING state
- Cannot cancel already CLEARED/BOUNCED/CANCELLED cheques
- Cancellation reason is mandatory
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
Difference from Bounce:
- Cancel: User-initiated, proactive stop payment
- Bounce: System-initiated, reactive return

Response (200 OK)

{
  "commandName": "InitiateCancelChequeCommand",
  "status": "Success",
  "data": {
    "chequeClearingId": "550e8400-e29b-41d4-a716-446655440000",
    "previousState": "PENDING",
    "newState": "CANCELLED",
    "accountNumber": "1001234567",
    "amount": 75000.00,
    "transactionType": "WITHDRAWAL",
    "cancellationReason": "CUSTOMER_REQUEST",
    "cancelledDate": "2025-12-31T14:00:00Z",
    "restoredBalance": 1000000.00
  }
}

Example: Stop Payment

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: 'InitiateCancelChequeCommand',
    data: {
      chequeClearingId: '660e8400-e29b-41d4-a716-446655440000',
      cancellationReason: 'CUSTOMER_REQUEST',
      remarks: 'Customer stop payment - cheque lost'
    }
  })
});

Error Responses

400 Bad Request - Invalid Amount

{
  "commandName": "InitiateChequeDepositCommand",
  "status": "Failed",
  "errors": ["Amount must be greater than zero"]
}

404 Not Found - Account Not Found

{
  "commandName": "InitiateChequeDepositCommand",
  "status": "Failed",
  "errors": ["Account not found: 1001234567"]
}

400 Bad Request - Account Frozen

{
  "commandName": "InitiateChequeDepositCommand",
  "status": "Failed",
  "errors": ["Account 1001234567 is frozen and cannot accept deposits"]
}

400 Bad Request - Insufficient Balance

{
  "commandName": "InitiateChequeWithdrawalCommand",
  "status": "Failed",
  "errors": ["Insufficient balance for withdrawal"]
}

400 Bad Request - Invalid State

{
  "commandName": "InitiateClearChequeCommand",
  "status": "Failed",
  "errors": ["Cannot clear cheque in state: CLEARED. Must be PENDING"]
}

Status Codes

Code	Description
200	Success - Transaction processed
400	Bad Request - Validation error
404	Not Found - Account/Till/Cheque not found
500	Internal Server Error

Integration Examples

TypeScript: Daily Clearing Batch

interface ClearingConfirmation {
  chequeNo: string;
  chequeClearingId: string;
  status: 'CLEARED' | 'RETURNED';
  returnReason?: string;
  reference: string;
}

async function processDailyClearing(confirmations: ClearingConfirmation[]) {
  console.log(`ðŸ”„ Processing ${confirmations.length} clearing confirmations`);

  for (const confirmation of confirmations) {
    try {
      if (confirmation.status === 'CLEARED') {
        // Clear cheque
        await fetch('https://api.banklingo.com/api/bpm/cmd', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${token}`
          },
          body: JSON.stringify({
            commandName: 'InitiateClearChequeCommand',
            data: {
              chequeClearingId: confirmation.chequeClearingId,
              clearingReference: confirmation.reference,
              remarks: 'T+2 clearing confirmed by NIBSS'
            }
          })
        });
        console.log(`âœ… Cleared: ${confirmation.chequeNo}`);
      } else {
        // Bounce cheque
        await fetch('https://api.banklingo.com/api/bpm/cmd', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${token}`
          },
          body: JSON.stringify({
            commandName: 'InitiateBounceChequeCommand',
            data: {
              chequeClearingId: confirmation.chequeClearingId,
              bounceReason: confirmation.returnReason,
              bounceReference: confirmation.reference,
              remarks: `Returned by clearing house: ${confirmation.returnReason}`
            }
          })
        });
        console.log(`ðŸ”„ Bounced: ${confirmation.chequeNo} - ${confirmation.returnReason}`);
      }
    } catch (error) {
      console.error(`âŒ Error processing ${confirmation.chequeNo}:`, error);
    }
  }
}

C#: Stop Payment Workflow

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Approval Workflow Examples

Example 1: High-Value Cheque Deposit with Approval

Step 1: Submit Cheque Deposit Requiring Approval

{
  "commandName": "InitiateChequeDepositCommand",
  "data": {
    "accountEncodedKey": "1001234567",
    "amount": 5000000.00,
    "chequeNo": "CH999888",
    "requireApproval": true,
    "remarks": "High-value cheque deposit - requires manager approval per bank policy"
  }
}

Response:

{
  "status": "Success",
  "data": {
    "transactionKey": "CHQ2026001001",
    "state": "APPROVAL_PENDING",
    "unclearedChequeAmount": 0,
    "balance": 10000000.00,
    "message": "Cheque deposit awaiting approval"
  }
}

Account State:

â³ Transaction in APPROVAL_PENDING state
â³ UnclearedChequeAmount: â‚¦0 (not increased yet)
â³ Balance: â‚¦10,000,000 (unchanged)
â³ Cheque NOT in clearing cycle

Step 2: Branch Manager Approves

{
  "commandName": "ApproveTransactionCommand",
  "data": {
    "transactionKey": "CHQ2026001001",
    "approverNotes": "Verified customer identity and cheque authenticity. Approved for clearing."
  }
}

Response:

{
  "status": "Success",
  "data": {
    "transactionKey": "CHQ2026001001",
    "state": "PENDING",
    "unclearedChequeAmount": 5000000.00,
    "balance": 10000000.00,
    "message": "Cheque approved and entered clearing cycle"
  }
}

Account State After Approval:

âœ… Transaction state: PENDING (clearing)
âœ… UnclearedChequeAmount: â‚¦5,000,000 (increased)
âœ… Balance: â‚¦10,000,000 (still unchanged, awaiting clearing)
âœ… Standard T+2 clearing period begins

Step 3: Clear Cheque After T+2

{
  "commandName": "InitiateClearChequeCommand",
  "data": {
    "chequeClearingId": "550e8400-e29b-41d4-a716-446655440000",
    "clearingReferenceId": "CLR2026010301",
    "remarks": "Cheque cleared successfully"
  }
}

Final Account State:

âœ… Transaction state: CLEARED
âœ… UnclearedChequeAmount: â‚¦0 (decreased)
âœ… Balance: â‚¦15,000,000 (credited)

Example 2: Rejected Cheque Deposit (Failed Approval)

Step 1: Submit Suspicious Cheque

{
  "commandName": "InitiateChequeDepositCommand",
  "data": {
    "accountEncodedKey": "1001234567",
    "amount": 2500000.00,
    "chequeNo": "CH777666",
    "requireApproval": true,
    "remarks": "Cheque deposit - unusual pattern detected, requires compliance review"
  }
}

Step 2: Compliance Officer Rejects

{
  "commandName": "RejectTransactionCommand",
  "data": {
    "transactionKey": "CHQ2026001002",
    "rejectionReason": "Cheque signature does not match specimen signature. Customer unable to provide additional identification. Transaction rejected per AML policy."
  }
}

Response:

{
  "status": "Success",
  "data": {
    "transactionKey": "CHQ2026001002",
    "state": "CANCELLED",
    "unclearedChequeAmount": 0,
    "balance": 10000000.00,
    "message": "Cheque deposit rejected and cancelled"
  }
}

Final State:

âŒ Transaction cancelled (never entered clearing)
âŒ UnclearedChequeAmount: â‚¦0 (never increased)
âŒ Balance: â‚¦10,000,000 (unchanged)
âŒ Customer notified of rejection

Example 3: High-Value Cheque Withdrawal with Approval

Step 1: Submit Large Cheque Withdrawal

{
  "commandName": "InitiateChequeWithdrawalCommand",
  "data": {
    "accountEncodedKey": "1001234567",
    "amount": 3000000.00,
    "chequeNo": "CH555444",
    "payeeName": "ABC Construction Ltd",
    "requireApproval": true,
    "remarks": "Large vendor payment - requires dual authorization"
  }
}

Response:

{
  "status": "Success",
  "data": {
    "transactionKey": "CHQ2026001003",
    "state": "APPROVAL_PENDING",
    "holdAmount": 3000000.00,
    "balance": 10000000.00,
    "availableBalance": 7000000.00,
    "message": "Cheque withdrawal awaiting approval"
  }
}

Account State:

â³ Transaction in APPROVAL_PENDING state
â³ HoldAmount: â‚¦3,000,000 (hold placed)
â³ Balance: â‚¦10,000,000 (not debited yet)
â³ Available Balance: â‚¦7,000,000 (reduced by hold)
â³ Cheque NOT issued yet

Step 2: Manager Approves Withdrawal

{
  "commandName": "ApproveTransactionCommand",
  "data": {
    "transactionKey": "CHQ2026001003",
    "approverNotes": "Verified contract with ABC Construction. Payment authorized. Cheque issued."
  }
}

Response:

{
  "status": "Success",
  "data": {
    "transactionKey": "CHQ2026001003",
    "state": "PENDING",
    "holdAmount": 0,
    "balance": 7000000.00,
    "availableBalance": 7000000.00,
    "message": "Cheque withdrawal approved and issued"
  }
}

Final State After Approval:

âœ… Transaction state: PENDING (clearing)
âœ… HoldAmount: â‚¦0 (hold released)
âœ… Balance: â‚¦7,000,000 (debited immediately)
âœ… Cheque issued to payee
âœ… Can be bounced if dishonored by clearing house

Example 4: Cancelled Cheque Withdrawal (Before Approval)

Step 1: Submit Withdrawal Request

{
  "commandName": "InitiateChequeWithdrawalCommand",
  "data": {
    "accountEncodedKey": "1001234567",
    "amount": 500000.00,
    "chequeNo": "CH333222",
    "payeeName": "XYZ Services",
    "requireApproval": true,
    "remarks": "Service payment"
  }
}

Step 2: Customer Cancels Before Approval

{
  "commandName": "CancelTransactionCommand",
  "data": {
    "transactionKey": "CHQ2026001004",
    "cancellationReason": "Customer request - payment method changed to bank transfer instead"
  }
}

Response:

{
  "status": "Success",
  "data": {
    "transactionKey": "CHQ2026001004",
    "state": "CANCELLED",
    "holdAmount": 0,
    "balance": 10000000.00,
    "availableBalance": 10000000.00,
    "message": "Cheque withdrawal cancelled successfully"
  }
}

Final State:

âŒ Transaction cancelled (before approval)
âŒ HoldAmount: â‚¦0 (hold released)
âŒ Balance: â‚¦10,000,000 (unchanged)
âŒ Cheque not issued

Example 5: Complete Workflow - Deposit with Approval and Clearing

Timeline: Day 1 - Deposit Submission

{
  "commandName": "InitiateChequeDepositCommand",
  "data": {
    "accountEncodedKey": "1001234567",
    "amount": 1500000.00,
    "chequeNo": "CH111222",
    "requireApproval": true,
    "remarks": "Third-party cheque - requires verification"
  }
}

Day 1 Status:

State: APPROVAL_PENDING
Balance: â‚¦10,000,000
UnclearedAmount: â‚¦0

Timeline: Day 1 - Manager Approval (2 hours later)

{
  "commandName": "ApproveTransactionCommand",
  "data": {
    "transactionKey": "CHQ2026001005",
    "approverNotes": "Third-party cheque verified with issuing bank. Approved."
  }
}

Day 1 Status After Approval:

State: PENDING (clearing cycle started)
Balance: â‚¦10,000,000
UnclearedAmount: â‚¦1,500,000
Clearing deadline: Day 3 (T+2)

Timeline: Day 3 - Cheque Clearing

{
  "commandName": "InitiateClearChequeCommand",
  "data": {
    "chequeClearingId": "550e8400-e29b-41d4-a716-446655440000",
    "clearingReferenceId": "CLR2026010501",
    "remarks": "Cheque cleared - funds available"
  }
}

Day 3 Final Status:

State: CLEARED
Balance: â‚¦11,500,000 (credited)
UnclearedAmount: â‚¦0
Transaction complete

Example 6: Dormant Account Cheque Withdrawal

{
  "commandName": "InitiateChequeWithdrawalCommand",
  "data": {
    "accountEncodedKey": "9008887777",
    "amount": 250000.00,
    "chequeNo": "CH999000",
    "payeeName": "Account Holder",
    "requireApproval": true,
    "remarks": "Withdrawal from dormant account (inactive 24 months) - requires special authorization and customer ID verification"
  }
}

Expected Workflow:

Transaction enters APPROVAL_PENDING
Compliance officer verifies customer identity
Account reactivation process initiated
Branch manager approves after KYC update
Account status: DORMANT â†’ ACTIVE
Transaction approved: APPROVAL_PENDING â†’ PENDING
Balance debited, cheque issued

Approval Notes Example:

{
  "commandName": "ApproveTransactionCommand",
  "data": {
    "transactionKey": "CHQ2026001006",
    "approverNotes": "Customer identity verified with national ID and biometric confirmation. Account reactivated per policy. KYC documents updated. Cheque withdrawal approved."
  }
}

Best Practices

For Developers

Always check state before clearing/bouncing/cancelling
Handle errors gracefully with proper error codes
Use transaction impacts for audit trail
Validate currency matching for till operations
Record all references from clearing house

For Tellers/Staff

Verify customer identity for stop payments
Document authorization for cancellations
Check account status before accepting cheques
Validate cheque details (date, amount, signature)
Issue receipts for all transactions

For Operations

Process clearing daily (T+2 standard)
Monitor aged cheques (>5 days pending)
Reconcile with clearing house reports
Track bounce rates per account/branch
Review cancellation patterns for fraud detection

Cheque Book Management

For cheque book registration and management, see Book Registers which provides unified management for cheque books, deposit slips, and withdrawal slips.

GetUnclearedChequeQuery - Query pending cheques for account
GetAllChequeClearingRequestsQuery - System-wide pending cheques

Overview​

Commands Summary​

Cheque Processing Workflow​

Key Behaviors​

Asymmetric Processing​

Approval Workflow​

Overview​

Transaction Approval States​

Direct Clearing Entry (No Approval Required)​

Approval Required Before Clearing​

State Transition with Approval Workflow​

Universal Transaction Management Commands​

1. Approve Transaction (APPROVAL_PENDING â†’ PENDING Clearing)​

2. Reject Transaction (APPROVAL_PENDING â†’ CANCELLED)​

3. Cancel Transaction (APPROVAL_PENDING â†’ CANCELLED)​

4. Reverse Transaction (After CLEARED/BOUNCED/CANCELLED)​

Approval Workflow Use Cases​

When to Use requireApproval = true​

When to Use requireApproval = false (Direct Clearing)​

Configuration Recommendations​

Relationship Between Approval and Clearing​

1. Cheque Deposit​

Request​

Parameters​

Business Logic​

Response (200 OK)​

Account State Impact​

Example: Basic Deposit​

2. Cheque Withdrawal​

Request​

Parameters​

Business Logic​

Response (200 OK)​

Account State Impact​

Example: Issue Cheque​

3. Clear Cheque​

Request​

Parameters​

Business Logic​

Response (200 OK)​

Clearing Timeline​

Example: Clear Deposit​

4. Bounce Cheque​

Request​

Parameters​

Bounce Reasons​

Business Logic​

Response (200 OK)​

Example: Bounce Deposit​

5. Cancel Cheque​

Request​

Parameters​

Cancellation Reasons​

Business Logic​

Response (200 OK)​

Example: Stop Payment​

Error Responses​

400 Bad Request - Invalid Amount​

404 Not Found - Account Not Found​

400 Bad Request - Account Frozen​

400 Bad Request - Insufficient Balance​

400 Bad Request - Invalid State​

Status Codes​

Integration Examples​

TypeScript: Daily Clearing Batch​

C#: Stop Payment Workflow​

Approval Workflow Examples​

Example 1: High-Value Cheque Deposit with Approval​

Example 2: Rejected Cheque Deposit (Failed Approval)​

Example 3: High-Value Cheque Withdrawal with Approval​

Example 4: Cancelled Cheque Withdrawal (Before Approval)​

Example 5: Complete Workflow - Deposit with Approval and Clearing​

Example 6: Dormant Account Cheque Withdrawal​

Best Practices​

For Developers​

For Tellers/Staff​

For Operations​

Related Commands​

Overview

Commands Summary

Cheque Processing Workflow

Key Behaviors

Asymmetric Processing

Approval Workflow

Overview

Transaction Approval States

Direct Clearing Entry (No Approval Required)

Approval Required Before Clearing

State Transition with Approval Workflow

Universal Transaction Management Commands

1. Approve Transaction (APPROVAL_PENDING â†’ PENDING Clearing)

2. Reject Transaction (APPROVAL_PENDING â†’ CANCELLED)

3. Cancel Transaction (APPROVAL_PENDING â†’ CANCELLED)

4. Reverse Transaction (After CLEARED/BOUNCED/CANCELLED)

Approval Workflow Use Cases

When to Use `requireApproval = true`

When to Use `requireApproval = false` (Direct Clearing)

Configuration Recommendations

Relationship Between Approval and Clearing

1. Cheque Deposit

Request

Parameters

Business Logic

Response (200 OK)

Account State Impact

Example: Basic Deposit

2. Cheque Withdrawal

Request

Parameters

Business Logic

Response (200 OK)

Account State Impact

Example: Issue Cheque

3. Clear Cheque

Request

Parameters

Business Logic

Response (200 OK)

Clearing Timeline

Example: Clear Deposit

4. Bounce Cheque

Request

Parameters

Bounce Reasons

Business Logic

Response (200 OK)

Example: Bounce Deposit

5. Cancel Cheque

Request

Parameters

Cancellation Reasons

Business Logic

Response (200 OK)

Example: Stop Payment

Error Responses

400 Bad Request - Invalid Amount

404 Not Found - Account Not Found

400 Bad Request - Account Frozen

400 Bad Request - Insufficient Balance

400 Bad Request - Invalid State

Status Codes

Integration Examples

TypeScript: Daily Clearing Batch

C#: Stop Payment Workflow

Approval Workflow Examples

Example 1: High-Value Cheque Deposit with Approval

Example 2: Rejected Cheque Deposit (Failed Approval)

Example 3: High-Value Cheque Withdrawal with Approval

Example 4: Cancelled Cheque Withdrawal (Before Approval)

Example 5: Complete Workflow - Deposit with Approval and Clearing

Example 6: Dormant Account Cheque Withdrawal

Best Practices

For Developers

For Tellers/Staff

For Operations

Related Commands