Set Collection Details

Overview

SetCollectionDetailsCommand configures the direct debit collection settings for an approved loan and auto-generates the full repayment schedule. It can be called multiple times — each call replaces the previous schedule entirely.

Prerequisites: The loan must exist and its associated product must have interest rate and tenor configured. Call ValidateBankAccountNumberCommand beforehand to verify the debit account details.

ValidateBankAccountNumberCommand contract

The account-validation command is used to verify the debit account before collection details are stored. The trigger is controlled by the request payload, not by a frontend-provided command name override.

Request payload

{
  "bankCode": "058",
  "accountNumber": "0123456789",
  "accountValidationSource": "NIBSS",
  "preValidationRequired": true,
  "postValidationRequired": false,
  "validationTrackerId": "loan-quote-1001-validation"
}

Supported flags

Field	Type	Required	Description
bankCode	string	Yes	Destination bank code for the account being validated
accountNumber	string	Yes	Destination account number
accountValidationSource	string	No	Validation source such as NIBSS; defaults to NIBSS
preValidationRequired	bool	No	If true and postValidationRequired is false, run the fixed validation chain before the normal account validation
postValidationRequired	bool	No	If true and preValidationRequired is false, run the fixed validation chain after the normal account validation
validationTrackerId	string	No	Tracker ID sent alongside the validation context so the downstream validation chain can correlate the request

Behavior

• If both preValidationRequired and postValidationRequired are false, the command performs the standard account validation flow and does not trigger the extra validation chain.
• If only preValidationRequired is true, the validation chain runs before account validation.
• If only postValidationRequired is true, the validation chain runs after account validation.
• validationStage is not required for this command. The boolean flags are the contract used by the application.

The fixed command chain used internally is:

cmdBankLingoValidateBankAccountNumber

Command Details

• Command: SetCollectionDetailsCommand
• Type: Command (write operation)

API Endpoint

POST /api/bpm/cmd

Request Structure

Field	Type	Required	Description
loanRequestId	long	Yes	ID of the loan quote (LoanQuote.Id)
repaymentDayInMonth	int	Yes	Calendar day (1–31) on which debit is attempted each month
repaymentCount	int	Yes	Total number of installments (must be ≥ 1)
collectionStartDate	string (ISO 8601)	Yes	Date of the first installment (e.g. "2025-09-01")
accountNumber	string	Yes	Borrower's bank account number to debit
accountName	string	Yes	Account holder's name
bankCode	string	Yes	NIBSS bank code or internal bank code
collectionMode	int	Yes	0 = GSI, 1 = Direct Debit (see Collection Modes)
enableAutoDebit	bool	No	Whether automated debit should be enabled (default: false)
comment	string	No	Optional officer comment

Collection Modes

Value	Name	Description
0	GSI	Global Standing Instruction — NIBSS sweeps across all borrower accounts
1	DirectDebit	NIBSS direct debit mandate against the specified account

Try It Out

POST/api/bpm/cmdSetCollectionDetailsCommand

Base URL

Bearer Token

Request Body

{ "cmd": "SetCollectionDetailsCommand", "data": { "loanRequestId": 1001, "repaymentDayInMonth": 15, "repaymentCount": 12, "collectionStartDate": "2025-09-15", "accountNumber": "0123456789", "accountName": "John Doe", "bankCode": "000013", "collectionMode": 1, "enableAutoDebit": true, "comment": "Collection details set after client confirmation" } }

Response Structure

{
  "response": {
    "isSuccessful": true,
    "statusCode": "00",
    "message": "Collection details set successfully and repayment schedule generated.",
    "data": {
      "loanQuoteId": 1001,
      "accountNumber": "0123456789",
      "accountName": "John Doe",
      "bankCode": "000013",
      "bankName": "GTBank",
      "repaymentDayInMonth": 15,
      "repaymentCount": 12,
      "collectionStartDate": "2025-09-15T00:00:00Z",
      "collectionMode": 1,
      "enableAutoDebit": true,
      "schedulePreview": [
        {
          "installmentNumber": 1,
          "dueDate": "2025-09-15",
          "principalAmount": 41666.67,
          "interestAmount": 5000.00,
          "totalDue": 46666.67,
          "outstandingBalance": 458333.33
        }
      ]
    }
  },
  "responseCode": "00",
  "responseDescription": "Success"
}

Validation Rules

Rule	Error Code	Message
Bank code does not exist	08	"The bank code does not exist"
repaymentDayInMonth outside 1–31	09	"The repayment day must be between 1 and 31"
repaymentCount < 1	09	"The repayment count cannot be less than 1"
Loan not found	04	"Loan request not found"
Loan product has no disbursed amount	09	Disbursement amount validation error

Schedule Regeneration

Each call to this command deletes and recreates the repayment schedule. This means:

• Calling it a second time corrects any errors from the first call
• Once the Hangfire background job has created mandates, regenerating the schedule does not automatically recreate or cancel those mandates — mandate management must be done separately

Related Commands

• Get Repayment Schedule — Retrieve the generated schedule
• Waive Installment — Mark an installment as settled outside the system
• Create GSI Mandate from Loan — Manually create mandates for this loan