Skip to main content
Use this endpoint to poll a batch after creating it, or to inspect the outcome of a reprocess attempt. It returns the full batch record plus every item, each with its own status.

​
Endpoint

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

​
Path parameters

​
bulkTransferId
string
required
The bulkTransferId returned when you created the batch.

​
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

​
status
boolean
true on success.
​
message
string
Human-readable outcome.
​
data.id
string
The bulk transfer ID (same as bulkTransferId).
​
data.bulkReference
string
Human-readable reference for this batch.
​
data.businessId
string
The business this batch belongs to.
​
data.batchName
string
The name you gave this batch on creation.
​
data.totalItems
integer
Total number of transfers in the batch.
​
data.completedItems
integer
Number of items currently in completed status.
​
data.failedItems
integer
Number of items currently in failed status.
​
data.status
string
Batch status — pending, processing, completed, failed, or partially_completed. See statuses.
​
data.failureReason
string
Set when the batch as a whole failed to start — either processing or a batch-level reprocess (e.g. an insufficient-funds check at the batch level, or no payment account found). null otherwise — this is distinct from any individual item’s errorMessage.
​
data.createdAt
string
ISO 8601 timestamp of when the batch was created.
​
data.items
array
Every transfer in the batch, in the same order you submitted them (itemIndex ascending).
​
data.items[].id
string
Unique ID for this item. Use this as itemId when reprocessing a single item.
​
data.items[].itemIndex
integer
The item’s position (0-based) in the original transfers array.
​
data.items[].amount
string
Amount for this transfer, in kobo.
​
data.items[].receiverAccountNumber
string
Destination account number for this transfer.
​
data.items[].receiverBankCode
string
Destination bank code for this transfer.
​
data.items[].retrievalReference
string
The reference you supplied for this transfer.
​
data.items[].transactionReference
string
The transaction reference currently associated with this item. Changes each time the item is reprocessed — see originalTransactionReference.
​
data.items[].originalTransactionReference
string
The transaction reference from this item’s very first processing attempt. Only present once the item has been reprocessed at least once.
​
data.items[].status
string
Item status — pending, processing, completed, or failed.
​
data.items[].errorMessage
string
Reason the item failed. Empty string if the item hasn’t failed.
​
data.items[].errorCode
string
Provider- or validation-supplied error code. Not a fixed enum — informational only.
​
data.items[].providerReference
string
The banking provider’s own reference for this transfer, once processed.
​
data.items[].reprocessCount
integer
Number of times this item has been reprocessed.
​
data.items[].processedAt
string
ISO 8601 timestamp of when this item last finished processing. null if still pending.

​
Code examples

curl -X GET https://sandbox.stellasbank.com/api/v1/clients/business/customers/funds/bulk-transfer/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/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/6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f",
    headers={
        "x-api-key": "stl_c8e286ca55b0123e0b05da047494f585",
        "x-api-secret": "stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0",
        "businessId": "YOUR_BUSINESS_ID",
    },
)
print(res.json()["data"])

​
Example response

{
  "status": true,
  "message": "Bulk transfer retrieved successfully",
  "data": {
    "id": "6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f",
    "bulkReference": "BULK-a1b2c3d4e5f6g7h8i9j0",
    "businessId": "biz_xyz789",
    "batchName": "July salaries",
    "totalItems": 2,
    "completedItems": 1,
    "failedItems": 1,
    "status": "partially_completed",
    "failureReason": null,
    "createdAt": "2024-07-01T09:00:00.000Z",
    "items": [
      {
        "id": "a1b2c3d4-0000-4a8d-9e2f-000000000001",
        "itemIndex": 0,
        "amount": "100000",
        "receiverAccountNumber": "1234567890",
        "receiverBankCode": "058",
        "retrievalReference": "salary_2024_07_001",
        "transactionReference": "TRX-abc123",
        "status": "completed",
        "errorMessage": "",
        "errorCode": "",
        "providerReference": "PRV-001",
        "reprocessCount": 0,
        "processedAt": "2024-07-01T09:00:05.000Z"
      },
      {
        "id": "a1b2c3d4-0000-4a8d-9e2f-000000000002",
        "itemIndex": 1,
        "amount": "200000",
        "receiverAccountNumber": "0987654321",
        "receiverBankCode": "058",
        "retrievalReference": "salary_2024_07_002",
        "transactionReference": "TRX-def456",
        "status": "failed",
        "errorMessage": "Insufficient Funds",
        "errorCode": "",
        "providerReference": "",
        "reprocessCount": 0,
        "processedAt": "2024-07-01T09:00:06.000Z"
      }
    ]
  }
}

​
Errors

StatusCause
401 UnauthorizedbusinessId header missing, or credentials invalid — see Errors
404 Not FoundNo bulk transfer with this ID exists for your client and business
Unlike Create a bulk transfer, a missing businessId header on this endpoint returns 401, not 400.