Manage a NIBSS GSI Batch

Add accounts

AddAccountToNibssGSIMandateBatchCommand adds one Building mandate per new account to an existing grouped NIBSS GSI batch.

The command requires all existing and incoming accounts to share one BVN. It validates the supplied bank through BANK_LIST_CONFIG, stores nibssMandateBankCode, and skips a bank/account pair that already exists. A batch is editable only while every mandate is Building (-1) and has no MandateCode.

POST/api/bpm/cmdAddAccountToNibssGSIMandateBatchCommand

Base URL

Bearer Token

Request Body

{ "cmd": "AddAccountToNibssGSIMandateBatchCommand", "data": { "batchId": 42, "accounts": [ { "accountNumber": "0098765432", "bvn": "22345678901", "bankCode": "033", "accountName": "John Doe" } ] } }

Successful insertion dispatches OnNibssMandateAccountAdded for entity type NibssMandateBatch. A duplicate-only request succeeds without inserting rows or dispatching the event.

The event context retains the origin of the batch. For example, an account added to a loan-linked batch has batchOrigin: "LoanLinkedGSI", isLoanLinked: true, originatingCommand: "CreateNibssGSIMandateFromLoanCommand", and eventCommand: "AddAccountToNibssGSIMandateBatchCommand".

Finalize the batch

FinalizeNibssGSIMandateBatchCommand closes the grouped GSI batch for editing and moves every mandate from Building (-1) to Draft (0), whose description is Ready for Submission.

POST/api/bpm/cmdFinalizeNibssGSIMandateBatchCommand

Base URL

Bearer Token

Request Body

{ "cmd": "FinalizeNibssGSIMandateBatchCommand", "data": { "batchId": 42, "comment": "All GSI accounts have been added" } }

Finalization is idempotent: finalizing an already-finalized batch succeeds without changing it again. Finalization is rejected if an entry has already been submitted to NIBSS, if the batch contains an unexpected mixture of workflow states, or if any entry has a missing payer address or a subscriber code outside NIBSS's 10-20 character range.

The command does not call NIBSS. CreateNewbatchMandateJob runs every minute and selects entries whose MandateCode is null and whose state is Draft. Building entries are therefore never submitted before finalization. The job repeats the payer-address and subscriber-code validation immediately before making the provider call, which also prevents older invalid Draft rows from reaching NIBSS.

Process events

Event	Status	Purpose
OnNibssMandateBatchCreated	Existing	A NIBSS batch was created. Creation commands now emit it.
OnNibssMandateBatchSubmitted	Existing	A batch was submitted to NIBSS.
OnNibssMandateBatchCompleted	Existing	Batch processing completed.
OnNibssMandateBatchFailed	Existing	Batch processing failed.
OnNibssMandateCreated	Existing	A mandate was created.
OnNibssMandateActivated	Existing	A mandate was activated.
OnNibssMandateSuspended	Existing	A mandate was suspended.
OnNibssMandateCancelled	Existing	A mandate was cancelled.
OnNibssMandateAccountAdded	Added	One or more accounts were appended to a grouped GSI batch.

Batch event context

All NIBSS batch events dispatched by these commands include the following stable routing fields:

Field	Description
batchOrigin	SingleMandate, StandaloneGSI, LoanLinkedGSI, or BatchUpload
batchOriginValue	Stable numeric value: 0, 1, 2, or 3, respectively
mandateType	Enum name: EMandate, GSI, or PaperMandate
mandateTypeValue	Enum value: 1, 2, or 3, respectively
mandateTypeDescription	Human-readable mandate type description
isGsi	true when the effective mandate type is GSI
isGroupedGSIMandate	true when the mandates are held in an editable grouped GSI batch
isLoanLinked	true only when the batch contains mandates linked to a loan quote
loanQuoteId	The linked loan quote ID, or 0 when the batch is not loan-linked
originatingCommand	Public command associated with the creation flow
eventCommand	Command that caused the current event

Use isLoanLinked for process routing. For example, a process intended only for non-loan mandate batches can use:

context.isLoanLinked === false

Example standalone GSI creation context:

{
  "batchOrigin": "StandaloneGSI",
  "batchOriginValue": 1,
  "isLoanLinked": false,
  "loanQuoteId": 0,
  "originatingCommand": "CreateNibssMandateCommand",
  "eventCommand": "CreateNibssMandateCommand",
  "mandateType": "GSI",
  "mandateTypeValue": 2,
  "mandateTypeDescription": "Global Standing Instruction (GSI)",
  "isGsi": true,
  "isGroupedGSIMandate": true,
  "mandateStatus": "Building",
  "mandates": [
    {
      "id": 701,
      "batchId": 42,
      "mandateType": "GSI",
      "mandateTypeValue": 2,
      "mandateTypeDescription": "Global Standing Instruction (GSI)",
      "isGsi": true,
      "isGroupedGSIMandate": true,
      "storedMandateType": "EMandate",
      "mandateStatus": "Building",
      "mandateStatusValue": -1,
      "productCode": "PR-2",
      "productName": "Payday",
      "loanQuoteId": 1001,
      "amount": 8000000,
      "debitAmount": 1000000,
      "numberOfInstallments": 8,
      "accountCount": 1,
      "accounts": [
        {
          "id": 801,
          "bankId": 10,
          "bankCode": "058",
          "accountNumber": "0123456789",
          "accountName": "Example Customer"
        }
      ]
    }
  ],
  "loan": {
    "id": 1001,
    "requestId": "00001PR-21001",
    "quoteId": "QUOTE-1001",
    "selfServiceUserId": 245,
    "initiatorSelfServiceUserId": 246,
    "productCode": "PR-2",
    "productName": "Payday",
    "currencyCode": "NGN",
    "requestedAmount": 8000000,
    "loanAmount": 7500000,
    "recommendedAmount": 7000000,
    "repaymentAmount": 8000000,
    "approvalState": "FullyApproved",
    "approvalStateValue": 3,
    "approvalStateDescription": "Fully Approved",
    "disbursementState": "PendingDisbursement",
    "disbursementStateValue": 1,
    "disbursementStateDescription": "Pending Disbursement",
    "branchId": 14,
    "loanTenor": 8,
    "loanTenorType": "MONTHS",
    "loanTenorTypeValue": 2,
    "loanTenorTypeDescription": "Month(s)"
  }
}

The mandates array is included for all mandate-batch events and contains one summary per mandate plus its account summaries. Base64 mandate documents and BVNs are deliberately excluded from the process context. The loan object is included only when isLoanLinked is true; it reuses the loan quote already loaded and validated by CreateNibssGSIMandateFromLoanCommand, so creating the context does not add another loan-query round trip.

Example loan-linked GSI creation context:

{
  "batchOrigin": "LoanLinkedGSI",
  "batchOriginValue": 2,
  "isLoanLinked": true,
  "loanQuoteId": 1001,
  "originatingCommand": "CreateNibssGSIMandateFromLoanCommand",
  "eventCommand": "CreateNibssGSIMandateFromLoanCommand",
  "mandateType": "GSI",
  "mandateTypeValue": 2,
  "mandateTypeDescription": "Global Standing Instruction (GSI)",
  "isGsi": true,
  "isGroupedGSIMandate": true,
  "mandateStatus": "Building"
}

CreateNibssMandateCommand also creates a batch and dispatches OnNibssMandateBatchCreated for electronic and paper mandates. Those events use batchOrigin: "SingleMandate" and isLoanLinked: false. CreateNibssMandateListCommand uses batchOrigin: "BatchUpload" and is also non-loan-linked.

State flow

Building (-1) -- FinalizeNibssGSIMandateBatchCommand --> Draft / Ready for Submission (0)
Draft (0) -- CreateNewbatchMandateJob --> NIBSS provider