Upload bulk transfer via Excel

New to bulk transfer? Read the overview first.

As an alternative to Create a bulk transfer with a JSON transfers array, you can upload an Excel spreadsheet instead. This flow has a few more steps than the JSON path, because recipient bank details in a spreadsheet haven’t been verified yet:

Upload the file — Interstellas parses it, creates the batch and its items, and kicks off recipient name verification in the background.
Poll the preview to see which rows resolved to a real account name and which didn’t.
Fix any rows that failed verification, one at a time.
Start processing, same as any other batch — see Process a bulk transfer.

Download the template

Interstellas Excel bulk upload template

Download the .xlsx template — start every upload from this file.

Use this exact template rather than building your own spreadsheet from scratch. Fill in your data under the existing headers, in the existing Sheet1, and upload it as-is — don’t rename the sheet, reorder/rename the header row, or save it out as a different file type. Anything else risks hitting the parsing errors described below.

The template also includes a hidden Bank List sheet listing every bank name Interstellas recognizes — unhide it in Excel if you need to check the exact spelling of a bank name before filling in the Bank column. Leave that sheet in place when you upload; only Sheet1 is read.

Excel file format

The template above already matches this format — this section is a reference for what it contains, not a spec to build your own file against.

The sheet must be named exactly Sheet1. Files in any other format, or missing this sheet, are rejected.

File type: .xlsx or .xls, up to 5 MB.
Row 1 must be a header row. Column order doesn’t matter, but the header text does — matched case-insensitively:

Header	Maps to	Required
`Bank`	Recipient’s bank name	Yes
`Account Number`	Recipient’s account number	Yes
`Amount`	Amount in kobo	Yes
`Narration`	Transfer narration	No

Bank must exactly match a recognized bank name (case-insensitive) — not a bank code. Use the Bank List sheet in the template to confirm valid spelling. An unrecognized name fails the whole upload; see Errors below.
Account Number — if Excel has converted your account numbers to plain numbers and dropped leading zeros, that’s fine: numbers are re-padded to 10 digits automatically.
Amount accepts ₦ and , characters and strips them (e.g. ₦5,000 and 5000 both parse fine) — but the underlying value must still be kobo, matching every other endpoint in this API. It must be a positive number.
Completely blank rows (every cell empty) are silently skipped rather than treated as errors.

Upload

Endpoint

POST /clients/business/customers/funds/bulk-transfer/upload

Send as multipart/form-data.

Headers

x-api-key

string

required

Your public API key.

x-api-secret

string

required

Your API secret. Use a stl_test_... value in sandbox, stl_live_... in production.

businessId

string

required

Your business ID.

Form fields

file

required

The filled-in Interstellas Excel bulk upload template, matching the format above.

batchName

string

required

A name for this batch, up to 255 characters. Must be unique among your business’s bulk transfers, same as Create a bulk transfer.

Response

status

boolean

true on success.

message

string

"Bulk transfer batch accepted".

data.bulkTransferId

string

Unique ID for this batch. Use this to poll the preview and to process the batch once you’re ready.

data.bulkReference

string

A human-readable reference for this batch.

data.totalItems

integer

The number of rows accepted from the spreadsheet.

data.status

string

Always "pending" in this response — recipient name verification hasn’t finished yet.

data.message

string

"Batch received. Recipient name verification is in progress." — a human-readable nudge to go poll the preview endpoint next.

Code examples

curl -X POST https://sandbox.stellasbank.com/api/v1/clients/business/customers/funds/bulk-transfer/upload \
  -H "x-api-key: stl_c8e286ca55b0123e0b05da047494f585" \
  -H "x-api-secret: stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0" \
  -H "businessId: YOUR_BUSINESS_ID" \
  -F "file=@payroll.xlsx" \
  -F "batchName=July salaries"

const form = new FormData();
form.append("file", fs.createReadStream("payroll.xlsx"));
form.append("batchName", "July salaries");

const res = await fetch(
  "https://sandbox.stellasbank.com/api/v1/clients/business/customers/funds/bulk-transfer/upload",
  {
    method: "POST",
    headers: {
      "x-api-key": "stl_c8e286ca55b0123e0b05da047494f585",
      "x-api-secret": "stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0",
      businessId: "YOUR_BUSINESS_ID",
      ...form.getHeaders(),
    },
    body: form,
  }
);
const { data } = await res.json();
const bulkTransferId = data.bulkTransferId;

import requests

with open("payroll.xlsx", "rb") as f:
    res = requests.post(
        "https://sandbox.stellasbank.com/api/v1/clients/business/customers/funds/bulk-transfer/upload",
        headers={
            "x-api-key": "stl_c8e286ca55b0123e0b05da047494f585",
            "x-api-secret": "stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0",
            "businessId": "YOUR_BUSINESS_ID",
        },
        files={"file": f},
        data={"batchName": "July salaries"},
    )
print(res.json())

Example response

{
  "status": true,
  "message": "Bulk transfer batch accepted",
  "data": {
    "bulkTransferId": "6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f",
    "bulkReference": "BULK-a1b2c3d4e5f6g7h8i9j0",
    "totalItems": 2,
    "status": "pending",
    "message": "Batch received. Recipient name verification is in progress."
  }
}

Errors

Status	Cause
`400 Bad Request`	No file uploaded, or `batchName` missing
`400 Bad Request`	Wrong file type — only `.xlsx`/`.xls` are accepted
`400 Bad Request`	File is larger than 5 MB
`400 Bad Request`	`"Sheet1" not found in workbook`, or the file has no data rows
`400 Bad Request`	One or more rows are missing a bank name, account number, or a valid positive amount — the message lists every offending row
`400 Bad Request`	One or more bank names couldn’t be matched to a known bank — the message lists which rows and names
`400 Bad Request`	More than 5,000 valid rows in the file
`409 Conflict`	`batchName` already exists for this business
`401 Unauthorized`	`businessId` header missing, or credentials invalid

Validation is all-or-nothing: if any row has a bad amount, missing account number, or unrecognized bank name, the entire upload is rejected and no batch is created. Fix the spreadsheet and re-upload.

Preview

Poll this to check the status of recipient name verification after uploading.

Endpoint

GET /clients/business/customers/funds/bulk-transfer/upload/preview/{bulkTransferId}

Path parameters

bulkTransferId

string

required

The ID returned from the upload response.

Headers

x-api-key

string

required

Your public API key.

x-api-secret

string

required

Your API secret. Use a stl_test_... value in sandbox, stl_live_... in production.

businessId

string

required

Your business ID.

Response

data.status

string

"pending" while verification is still running, "enquiry_complete" once every row has been checked. This is a distinct value from the batch statuses used elsewhere — it only applies to uploaded batches before you start processing.

data.totalAmount

string

Sum of every row’s amount, in kobo.

data.resolvedItems

integer

Number of rows whose recipient name was successfully verified.

data.failedItems

integer

Number of rows whose recipient name could not be verified.

data.pendingItems

integer

Number of rows still being checked. Poll again until this reaches 0.

data.items

array

Every row from the spreadsheet, in order.

data.items[].id

string

The item’s ID — use this with Edit an item below.

data.items[].receiverAccountNumber

string

The account number for this row.

data.items[].receiverBankName

string

The bank name for this row, as resolved back from the bank code Interstellas matched it to.

data.items[].amount

string

The amount for this row, in kobo.

data.items[].recipientName

string

The verified account holder name, once resolved. null until then, or if verification failed.

data.items[].nameEnquiryStatus

string

pending, resolved, or failed.

data.items[].nameEnquiryError

string

Why verification failed, if it did. null otherwise.

data.completedItems and data.failedItems at the top level of this response (inherited from the batch record’s own fields) currently mean name-enquiry outcomes, not transfer outcomes — they’re set to the same counts as resolvedItems/failedItems while the batch is pending/enquiry_complete. Once you call Process a bulk transfer and items actually start moving money, these same field names on Get a bulk transfer switch to meaning completed/failed transfers. Prefer resolvedItems/failedItems/pendingItems on this endpoint specifically, since their names aren’t ambiguous.

Code examples

curl -X GET https://sandbox.stellasbank.com/api/v1/clients/business/customers/funds/bulk-transfer/upload/preview/6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f \
  -H "x-api-key: stl_c8e286ca55b0123e0b05da047494f585" \
  -H "x-api-secret: stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0" \
  -H "businessId: YOUR_BUSINESS_ID"

const res = await fetch(
  "https://sandbox.stellasbank.com/api/v1/clients/business/customers/funds/bulk-transfer/upload/preview/6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f",
  {
    headers: {
      "x-api-key": "stl_c8e286ca55b0123e0b05da047494f585",
      "x-api-secret": "stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0",
      businessId: "YOUR_BUSINESS_ID",
    },
  }
);
const { data } = await res.json();

import requests

res = requests.get(
    "https://sandbox.stellasbank.com/api/v1/clients/business/customers/funds/bulk-transfer/upload/preview/6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f",
    headers={
        "x-api-key": "stl_c8e286ca55b0123e0b05da047494f585",
        "x-api-secret": "stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0",
        "businessId": "YOUR_BUSINESS_ID",
    },
)
print(res.json())

Example response

{
  "status": true,
  "message": "Bulk transfer preview retrieved",
  "data": {
    "id": "6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f",
    "bulkReference": "BULK-a1b2c3d4e5f6g7h8i9j0",
    "batchName": "July salaries",
    "totalItems": 2,
    "status": "enquiry_complete",
    "totalAmount": "300000",
    "resolvedItems": 1,
    "failedItems": 1,
    "pendingItems": 0,
    "items": [
      {
        "id": "a1b2c3d4-0000-4a8d-9e2f-000000000001",
        "itemIndex": 0,
        "receiverAccountNumber": "1234567890",
        "receiverBankCode": "058",
        "receiverBankName": "GTBank",
        "amount": "100000",
        "narration": "July salary",
        "recipientName": "Ada Lovelace",
        "nameEnquiryStatus": "resolved",
        "nameEnquiryError": null,
        "status": "pending"
      },
      {
        "id": "a1b2c3d4-0000-4a8d-9e2f-000000000002",
        "itemIndex": 1,
        "receiverAccountNumber": "0000000000",
        "receiverBankCode": "058",
        "receiverBankName": "GTBank",
        "amount": "200000",
        "narration": "July salary",
        "recipientName": null,
        "nameEnquiryStatus": "failed",
        "nameEnquiryError": "Unable to resolve account name",
        "status": "pending"
      }
    ]
  }
}

Errors

Status	Cause
`400 Bad Request`	`businessId` header missing
`404 Not Found`	No bulk transfer with this ID exists for your client and business
`401 Unauthorized`	Credentials invalid

Edit an item

Fix a row before processing — most commonly used to correct a row whose nameEnquiryStatus came back failed.

This only works while the batch’s status is pending or enquiry_complete. Once you’ve called Process a bulk transfer, items can no longer be edited this way.

Endpoint

PATCH /clients/business/customers/funds/bulk-transfer/{bulkTransferId}/items/{itemId}

Path parameters

bulkTransferId

string

required

The batch the item belongs to.

itemId

string

required

The item’s id, from the preview response.

Headers

x-api-key

string

required

Your public API key.

x-api-secret

string

required

Your API secret. Use a stl_test_... value in sandbox, stl_live_... in production.

businessId

string

required

Your business ID.

Request body

At least one of the following is required.

receiverAccountNumber

string

Corrected account number.

receiverBankName

string

Corrected bank name — same matching rules as the Excel file format above (exact name match, case-insensitive).

amount

string

Corrected amount, in kobo.

narration

string

Corrected narration.

Changing receiverAccountNumber or receiverBankName automatically re-runs name verification for this item before responding — the item’s nameEnquiryStatus, recipientName, and nameEnquiryError in the response already reflect the new lookup. Changing only amount or narration does not trigger a re-check.

Response

Returns the full updated item — the same shape as an entry in the preview endpoint’s items array, plus a few internal bookkeeping fields (transactionReference, reprocessCount, etc. — all still null/0 at this stage since nothing has been processed yet).

Code examples

curl -X PATCH https://sandbox.stellasbank.com/api/v1/clients/business/customers/funds/bulk-transfer/6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f/items/a1b2c3d4-0000-4a8d-9e2f-000000000002 \
  -H "x-api-key: stl_c8e286ca55b0123e0b05da047494f585" \
  -H "x-api-secret: stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0" \
  -H "businessId: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverAccountNumber": "1234567891"
  }'

const res = await fetch(
  "https://sandbox.stellasbank.com/api/v1/clients/business/customers/funds/bulk-transfer/6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f/items/a1b2c3d4-0000-4a8d-9e2f-000000000002",
  {
    method: "PATCH",
    headers: {
      "x-api-key": "stl_c8e286ca55b0123e0b05da047494f585",
      "x-api-secret": "stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0",
      businessId: "YOUR_BUSINESS_ID",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ receiverAccountNumber: "1234567891" }),
  }
);
const { data } = await res.json();

import requests

res = requests.patch(
    "https://sandbox.stellasbank.com/api/v1/clients/business/customers/funds/bulk-transfer/6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f/items/a1b2c3d4-0000-4a8d-9e2f-000000000002",
    headers={
        "x-api-key": "stl_c8e286ca55b0123e0b05da047494f585",
        "x-api-secret": "stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0",
        "businessId": "YOUR_BUSINESS_ID",
    },
    json={"receiverAccountNumber": "1234567891"},
)
print(res.json())

Example response

{
  "status": true,
  "message": "Bulk transfer item updated",
  "data": {
    "id": "a1b2c3d4-0000-4a8d-9e2f-000000000002",
    "bulkTransferId": "6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f",
    "itemIndex": 1,
    "amount": "200000",
    "receiverAccountNumber": "1234567891",
    "receiverBankCode": "058",
    "narration": "July salary",
    "recipientName": "Grace Hopper",
    "nameEnquiryStatus": "resolved",
    "nameEnquiryError": null,
    "status": "pending"
  }
}

Errors

Status	Cause
`400 Bad Request`	No fields provided to update
`400 Bad Request`	`receiverBankName` couldn’t be matched to a known bank
`404 Not Found`	Batch or item not found for your client and business
`409 Conflict`	Batch `status` is no longer `pending` or `enquiry_complete` — processing has already started
`401 Unauthorized`	`businessId` header missing, or credentials invalid

See Errors for the full envelope and error code reference.

Ready to process

Once every row you care about shows nameEnquiryStatus: "resolved", start the batch the same way as any other bulk transfer:

Process a bulk transfer

Start executing the transfers in this batch.

Rows still failed at this point aren’t blocked from processing — Interstellas doesn’t check nameEnquiryStatus before attempting a transfer. An unresolved row will most likely fail again during processing, for the same reason it failed name verification, but it’s not guaranteed to be excluded automatically. Fix or remove anything you don’t want attempted before calling process.

​Download the template

Interstellas Excel bulk upload template

​Excel file format

​Upload

​Endpoint

​Headers

​Form fields

​Response

​Code examples

​Example response

​Errors

​Preview

​Endpoint

​Path parameters

​Headers

​Response

​Code examples

​Example response

​Errors

​Edit an item

​Endpoint

​Path parameters

​Headers

​Request body

​Response

​Code examples

​Example response

​Errors

​Ready to process

Process a bulk transfer

Download the template

Excel file format

Upload

Endpoint

Headers

Form fields

Response

Code examples

Example response

Errors

Preview

Endpoint

Path parameters

Headers

Response

Code examples

Example response

Errors

Edit an item

Endpoint

Path parameters

Headers

Request body

Response

Code examples

Example response

Errors

Ready to process