Bulk transfers overview

Bulk transfer lets you submit a batch of up to 5,000 individual bank transfers in one API call. Interstellas creates a record for the batch and for every line item inside it; you then explicitly start processing, and each transfer executes in the background. You track progress by polling the batch (or a single item), and you can selectively retry whatever failed — without resubmitting the transfers that already succeeded. This page explains the concepts that apply across every bulk transfer endpoint. For request/response details, see:

​

How it works

1. You submit a batch. A POST request with a batchName and a transfers array — one entry per payment you want to make. Interstellas validates the batch, writes a row for the batch and one row per transfer, and responds immediately with 201 Created. Nothing has been paid out yet at this point — every item starts in pending.
2. You start processing. Batches don’t begin executing on their own — call Process a bulk transfer with the bulkTransferId right after creating it. This queues every pending item for background execution and returns 202 Accepted immediately.
3. Interstellas processes items in the background. Each item moves through pending → processing → completed or failed independently. There’s no webhook for this today — poll Get a bulk transfer to watch progress.
4. The batch status reflects its items. Once every item has reached a final state, the batch itself settles into completed (all items succeeded), failed (none succeeded), or partially_completed (a mix).
5. You reprocess what failed. If any items end up failed, you can retry all of them at once or one at a time — see Reprocess. Items that already completed are never touched by a retry.

​

Statuses

​

Batch (status on the bulk transfer)

​

Item (status on each transfer within items)

​

Why an item fails

errorMessage on a failed item is a human-readable description of what went wrong. Common causes include:

• Recipient account validation failed — the account number/bank code combination couldn’t be verified before the transfer was attempted.
• Insufficient funds — your business account didn’t have enough available balance to cover the transfer at the moment it was processed. Because items are processed after the batch is accepted, this can happen even though the batch itself was created successfully.
• The receiving bank or provider rejected the transfer — surfaced with whatever reason the provider returned.

errorCode is provider- or validation-supplied and not a fixed enum — treat it as informational context alongside errorMessage, not a value to branch your application logic on.

​

Idempotency and uniqueness

• batchName must be unique per business. Submitting the same batchName twice returns 409 Conflict rather than creating a duplicate batch — use this to safely retry a batch creation request without double-submitting if your client times out.
• retrievalReference on each transfer must be unique across your business’s transfer history, not just within the batch. Reusing one — even from a previous batch — is rejected.

​

Reprocessing in depth

Reprocessing a failed item doesn’t reuse the original transaction reference — Interstellas generates a new transaction reference for each attempt and keeps the very first one around as originalTransactionReference, so you can always trace an item back to its first attempt even after several retries. reprocessCount tracks how many times an item has been retried. Reprocessing is asynchronous, same as the original batch: the reprocess endpoints return 202 Accepted immediately, and you poll Get a bulk transfer (or the item’s own reprocess logs) to see the outcome. Every retry — successful or not — is recorded as a reprocess log entry you can query independently of the batch/item’s current state.

​

Field naming

Bulk transfer responses use camelCase field names throughout (bulkReference, totalItems, receiverAccountNumber, and so on) — this differs in casing convention from a couple of older endpoints elsewhere in this API, but is consistent across every bulk transfer response.

​

Amounts

As with every other transfer endpoint in this API, amount is denominated in kobo (the smallest unit of NGN) and sent as a string, e.g. "100000" for ₦1,000.