Skip to main content

Create NIBSS GSI Mandate from Loan

Overview​

The CreateNibssGSIMandateFromLoanCommand creates a GSI mandate batch pre-populated from an existing Loan Quote. The mandate uses the loan product's existing code and name from loanProductConfiguration; branch, payer details, amounts, and schedule are resolved automatically from the loan quote and its collection information.

If the loan quote already has a grouped NIBSS GSI batch, the command reuses that batch and adds only new accounts. It does not create another batch. Repeating the same bank/account pair is idempotent and is reported as skipped.

New entries start in Building (-1). After all accounts have been added, call FinalizeNibssGSIMandateBatchCommand to move the entries to Draft (0, Ready for Submission), making them eligible for the background submission job.

Command Details​

  • Command: CreateNibssGSIMandateFromLoanCommand
  • Type: Command

API Endpoint​

POST /api/bpm/cmd

Request Structure​

Required fields (cannot be sourced from the loan quote)​

FieldTypeRequiredDescription
loanQuoteIdlongYesID of the existing Loan Quote to source mandate data from
organisationCodestringYesOrganisation code for the mandate
clientCodestringYesClient identifier code
accountsarrayYesBank accounts to attach (see below)

Optional fields​

FieldTypeRequiredDescription
narrationstringNoPayment narration / description
payerAddressstringNoOptional override. When omitted, the latest usable SelfServiceAddressInformation row for the loan customer is formatted and used.
tagstringNoOptional tag for categorisation

Each item in accounts​

FieldTypeRequiredDescription
accountNumberstringYesAccount number
bvnstringYesBank Verification Number — all accounts must share the same BVN
bankCodestringYesCBN bank code
accountNamestringYesAccount holder name

Auto-populated from Loan Quote​

The following fields are resolved automatically and do not need to be supplied:

FieldResolved from
loanProductCodeLoanQuote.LoanProductCode
productCodeThe matching loanProductConfiguration.loanProducts[].code
productNameThe matching loanProductConfiguration.loanProducts[].name
branchCodeLoanQuote.SelfServiceBranch.Code
payerNameLoanQuote.SelfServiceUser.UserDetail.DisplayName
payerAddressRequest override, otherwise the latest LoanQuote.SelfServiceUser.AddressInformations row (the same source exposed by GetCustomerAddressDetailsQuery)
mobileNumberLoanQuote.SelfServiceUser.UserDetail.MobileNumber
emailAddressLoanQuote.SelfServiceUser.EmailAddress
amountCollectionInfo.TotalCollectionAmount or LoanQuote.RepaymentAmount
debitAmountCollectionInfo.AmountPerCollection
numberOfInstallmentsCollectionInfo.RepaymentCount
startDateCollectionInfo.CollectionStartDate or LoanQuote.StartDate
endDateLoanQuote.EndDate
subscriberCodeLoanQuote.RequestId; the stored value is unchanged, while the outbound NIBSS value is padded when shorter than 10 characters

Validations​

  • Accounts appended later must use the same BVN as every existing account in the batch.

  • Accounts can only be appended while every entry is still Building and has no NIBSS MandateCode.

  • The persisted bank code is the configured nibssMandateBankCode, not the caller's unvalidated value.

  • All accounts in the accounts array must have the same BVN — cross-BVN GSI batches are rejected.

  • amount must equal debitAmount × numberOfInstallments.

  • startDate must not be in the past.

  • Required fields resolved from the loan quote that are null or empty will return a descriptive error.

  • A non-empty payer address is required. If neither the request nor the customer's saved address supplies one, the command returns NIBSS_PAYER_ADDRESS_REQUIRED before inserting a mandate or batch.

  • The normal loan request ID remains stored unchanged (for example, PR-2-163). At submission time only, its final numeric segment is left-padded with zeroes until the complete NIBSS subscriberCode is at least 10 characters (PR-2-163 becomes PR-2-00163). Values already between 10 and 20 characters are not padded.

Product classification configuration​

The loan quote already supplies LoanProductCode. That code must exist in loanProductConfiguration; the same configured code, name, and description classify the NIBSS GSI mandate. No separate mandate-product list or mapping is required.

# loanProductConfiguration
loanProducts:
  - name: Payroll
    code: PR-1
    description: Payroll loan repayment mandate
    # The code and name above are also used for the GSI mandate classification.
    # other loan settings...

Try It Out​

POST/api/bpm/cmdCreateNibssGSIMandateFromLoanCommand
Request Body

Response Structure​

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "NIBSS GSI mandate batch created from loan quote 1001 with 2 mandate(s).",
  "data": {
    "batchId": 42,
    "batchName": "NIBSS-GSI-L1001-240626120000",
    "loanQuoteId": 1001,
    "isGroupedGSIMandate": true,
    "serviceProvider": "NIBSS",
    "totalMandates": 2,
    "autoPopulatedFields": {
      "loanProductCode": "PR-1",
      "productCode": "PR-1",
      "productName": "Payroll",
      "branchCode": "BR-001",
      "payerName": "John Doe",
      "payerAddress": "15 Marina Street, Lagos",
      "mobileNumber": "08012345678",
      "emailAddress": "john@example.com",
      "amount": 1200000.00,
      "debitAmount": 100000.00,
      "numberOfInstallments": 12,
      "startDate": "2026-07-01",
      "endDate": "2027-06-30"
    },
    "mandates": [
      {
        "clientCode": "CLT-001",
        "payerName": "John Doe",
        "account": { "accountNumber": "0012345678", "bankCode": "058", "accountName": "John Doe" }
      }
    ]
  }
}