Skip to main content

Cheque Operations API

Complete developer guide for all cheque-related operations in BankLingo, including transaction processing, registration management, and clearing queries.

API Categories​

1. Cheque Transaction Commands (BPMCore V2)​

Process cheque transactions through their complete lifecycle - from deposit/withdrawal to clearing and settlement.

Implementation: CB.Administration.Api/Commands/BPMCore/Tellering/AdministrationCoreTelleringChequeCommandHandlers.cs

CommandPurposeEndpoint
InitiateChequeDepositCommandDeposit a cheque (PENDING state)POST /api/bpm/cmd
InitiateChequeWithdrawalCommandIssue cheque withdrawalPOST /api/bpm/cmd
InitiateClearChequeCommandClear pending cheque (PENDING → CLEARED)POST /api/bpm/cmd
InitiateBounceChequeCommandBounce cheque (reversal)POST /api/bpm/cmd
InitiateCancelChequeCommandCancel cheque (user-initiated reversal)POST /api/bpm/cmd

Key Features:

  • ✅ Complete V2 BPMCore implementation
  • ✅ Transaction impact tracking
  • ✅ Multi-day clearing cycle support
  • ✅ Asymmetric deposit/withdrawal handling
  • ✅ Local vs remote cheque processing
  • ✅ UnclearedChequeAmount tracking
Cheque Book Registration - See Book Registers

Cheque book registration commands have been replaced by the more comprehensive Book Registers system in BPMCore V2.

Book Registers provide expanded functionality:

  • ✅ Manages 3 book types: Cheque books, Deposit Slips, Withdrawal Slips
  • ✅ Enhanced security with BLOCKED state for fraud prevention
  • ✅ Unified management for all physical banking instruments
  • ✅ Modern BPMCore V2 architecture with Redis caching

For cheque book management, use:

See the Book Registers documentation for complete details.

2. Cheque Clearing Queries​

Query pending cheques and clearing requests for processing and monitoring.

QueryPurposeEndpoint
GetUnclearedChequeQueryGet pending cheques for accountPOST /api/bpm/cmd
GetAllChequeClearingRequestsQueryGet all pending clearing requestsPOST /api/bpm/cmd

Key Features:

  • ✅ Filter by account, date range, status
  • ✅ Pagination support
  • ✅ Real-time clearing status

Common Endpoints​

All cheque operations use the unified BPMCore command endpoint:

POST /api/bpm/cmd
Content-Type: application/json
Authorization: Bearer {token}

Request Structure​

{
  "commandName": "InitiateChequeDepositCommand",
  "data": {
    // Command-specific parameters
  }
}

Response Structure​

{
  "isSuccessful": true,
  "message": "Operation completed successfully",
  "statusCode": "00",
  "data": {
    // Command-specific response data
  }
}

Authentication​

All cheque operations require authentication:

Authorization: Bearer {access_token}

Obtain access token via Admin Login or Authenticator Login.

Cheque Processing Lifecycle​

1. Cheque Book Issuance​

CREATE REGISTRATION (Inactive) 
  → ACTIVATE REGISTRATION 
  → Customer receives cheque book
  → Cheques can be used

2. Cheque Deposit Processing​

INITIATE DEPOSIT (PENDING)
  → Cheque submitted to clearing house
  → CLEAR CHEQUE (PENDING → CLEARED)
  → Funds credited to account

OR

INITIATE DEPOSIT (PENDING)
  → Clearing fails
  → BOUNCE CHEQUE (PENDING → BOUNCED)
  → Account debited (if instant credit given)

3. Cheque Withdrawal Processing​

INITIATE WITHDRAWAL (PENDING)
  → Account debited immediately
  → Cheque presented by beneficiary
  → CLEAR CHEQUE (PENDING → CLEARED)
  → Settlement completed

OR

INITIATE WITHDRAWAL (PENDING)
  → Customer requests cancellation
  → CANCEL CHEQUE (PENDING → CANCELLED)
  → Account credited (reversal)

Key Entities​

ChequeClearingTransaction​

Represents a cheque in the clearing process.

Key Fields:

  • ChequeNo: Cheque serial number
  • ChequeAmount: Transaction amount
  • ChequeClearingState: PENDING | CLEARED | BOUNCED | CANCELLED
  • ChequeClearingTransactionType: DEPOSIT | WITHDRAWAL
  • DepositAccountNumber: Account number
  • TillAccountId: Associated till (for teller transactions)
  • RequestDate: When cheque was submitted
  • CBSTransactionId: Parent transaction reference

ChequeRegistration​

Represents an issued cheque book.

Key Fields:

  • DepositAccountId: Account that owns the book
  • StartSerialNumber: First cheque number
  • EndSerialNumber: Last cheque number
  • NumberOfLeaves: Total cheques in book
  • IsActive: Active status
  • IssuedDate: Date issued
  • ChequeRegistrationStatus: ACTIVE | NOT_ACTIVE

Error Codes​

CodeMessageCauseResolution
00SuccessOperation successfulNone
05Account inactiveAccount not ACTIVEActivate account
12Invalid cheque dataInvalid amount/numberVerify cheque details
14Invalid bank codeBank not foundCheck bank code
26Duplicate chequeAlready processedCheck transaction history
27Stale chequeCheque > 6 months oldRequest new cheque
28Post-dated chequeDate in futureWait until cheque date
51Insufficient fundsLow balanceDeposit funds
57Cheque stopped/stolenStop payment setContact issuer
58Signature mismatchInvalid signatureVerify signature
91System errorTechnical failureRetry or contact support

Best Practices​

For Developers​

  1. State Machine: Always follow proper state transitions (PENDING → CLEARED/BOUNCED/CANCELLED)
  2. Impact Tracking: Use TransactionImpactRecord for all balance changes
  3. Idempotency: Use unique transaction keys to prevent duplicates
  4. Error Handling: Implement retry logic for network failures
  5. Async Processing: Use background jobs for clearing operations
  6. Validation: Verify cheque registration is active before processing

For Operations​

  1. Monitor Clearing Queue: Review pending cheques daily
  2. Serial Number Management: Avoid overlapping ranges
  3. Deactivation Process: Deactivate lost/stolen books immediately
  4. Audit Trail: Maintain complete history of all operations
  5. Reconciliation: Daily reconciliation of cleared vs pending
  6. Security: Monitor for suspicious patterns (multiple bounces, large amounts)

Support​

For technical support or questions: