Create Remita Collection Batch

Overview

Creates a new collection batch by uploading a list of loan items in a single call. Each item in the items array creates a new RemitaLoanRequest (in Draft status) and links it to the batch. The batch is created in Initiated status and must be authorized before it can be run.

This is the primary entry point for bulk Remita loan onboarding — equivalent to the legacy UploadRemittaBatchCommand.

Command Details

• Command: CreateRemitaCollectionBatchCommand
• Type: Command

API Endpoint

POST /api/bpm/cmd

Request Structure

Field	Type	Required	Description
batchName	string	No	Name for the batch — auto-generated if omitted
batchDescription	string	No	Optional description or label
organisationId	long	Yes	Organisation the batch belongs to
items	array	Yes	List of loan entries to create (see below)

Item Fields (items[])

Field	Type	Required	Description
accountNumber	string	Yes	Borrower's bank account number
bankCode	string	No	CBN bank code
loanAmount	decimal	Yes	Total loan amount (must be > 0)
collectionAmount	decimal	Yes	Monthly deduction amount (must be > 0)
numberOfRepayments	int	No	Number of repayments (alias: tenure)
phoneNumber	string	Yes	Mobile number — minimum 11 digits (alias: mobileNumber)
loanAccount	string	No	Account to receive disbursed funds
companyName	string	No	Borrower's employer name — defaults to organisation name
accountName	string	No	Name on the account
cif	string	No	Customer Information File ID (default: NO_PROFILE)
bvn	string	No	Bank Verification Number
email	string	No	Borrower's email address
interestRate	decimal	No	Annual interest rate (default: 0)
tag	string	No	Loan category tag

Validation

All items are validated before any records are saved. If any item fails validation, the entire batch is rejected with the offending phone number and reason.

Try It Out

POST/api/bpm/cmdCreateRemitaCollectionBatchCommand

Base URL

Bearer Token

Request Body

{ "cmd": "CreateRemitaCollectionBatchCommand", "data": { "batchName": "March 2026 Salary Deductions", "batchDescription": "Monthly Remita loan repayment batch", "organisationId": 1001, "items": [ { "accountNumber": "0012345678", "bankCode": "058", "loanAmount": 500000, "collectionAmount": 50000, "numberOfRepayments": 12, "phoneNumber": "08012345678", "loanAccount": "LA-001", "companyName": "Federal Ministry of Finance", "accountName": "John Doe" }, { "accountNumber": "0098765432", "bankCode": "033", "loanAmount": 300000, "collectionAmount": 30000, "numberOfRepayments": 10, "phoneNumber": "08098765432", "loanAccount": "LA-002" } ] } }

Response Structure

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Batch uploaded successfully. 2 loan request(s) created.",
  "data": {
    "id": 3001,
    "batchName": "March 2026 Salary Deductions",
    "batchStatus": 0,
    "batchStatusDesc": "Initiated",
    "totalCount": 2,
    "totalAmount": 800000.00,
    "loanRequestCount": 2
  }
}

Validation Error (single item fails)

{
  "isSuccessful": false,
  "message": "08098765432: The loan amount must be greater than 0."
}

What Happens Next

Each item creates a RemitaLoanRequest with:

• Status = Draft
• MandateActivationStatus = NotActivated
• DisbursementChannel = External (loans were already disbursed externally)

The batch proceeds through this flow:

Initiated → Authorized → Processing → Completed

1. Authorize the batch — Authorize Collection Batch
2. Run the batch to trigger collections — Run Collection Batch
3. Monitor individual collections — Retrieve Collection Batches

Related Operations

• Authorize Collection Batch — Authorize the batch for execution
• Run Collection Batch — Execute all collections in the batch
• Retrieve Collection Batches — List batch records