Get a bulk transfer

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

string

required

The bulkTransferId returned when you created the batch.

Headers

string

required

Your public API key.

string

required

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

string

required

Your business ID.

Response

boolean

true on success.

string

Human-readable outcome.

string

The bulk transfer ID (same as bulkTransferId).

string

Human-readable reference for this batch.

string

The business this batch belongs to.

string

The name you gave this batch on creation.

integer

Total number of transfers in the batch.

integer

Number of items currently in completed status.

integer

Number of items currently in failed status.

string

Batch status — pending, processing, completed, failed, or partially_completed. See statuses.

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.

string

ISO 8601 timestamp of when the batch was created.

array

Every transfer in the batch, in the same order you submitted them (itemIndex ascending).

string

Unique ID for this item. Include it in itemIds when reprocessing items.

integer

The item’s position (0-based) in the original transfers array.

string

Amount for this transfer, in kobo.

string

Destination account number for this transfer.

string

Destination bank code for this transfer.

string

The reference you supplied for this transfer.

string

The transaction reference currently associated with this item. Changes each time the item is reprocessed — see originalTransactionReference.

string

The transaction reference from this item’s very first processing attempt. Only present once the item has been reprocessed at least once.

string

Item status — pending, processing, completed, or failed.

string

Reason the item failed. Empty string if the item hasn’t failed.

string

Provider- or validation-supplied error code. Not a fixed enum — informational only.

string

The banking provider’s own reference for this transfer, once processed.

integer

Number of times this item has been reprocessed.

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

Status	Cause
`401 Unauthorized`	`businessId` header missing, or credentials invalid — see Errors
`404 Not Found`	No 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.

Overview

Members

Business

Virtual accounts

Funds

Bulk transfers

Disputes

Subscriptions

Payouts

Audit logs

Settings

Endpoint

Path parameters

Headers

Response

Code examples

Example response

Errors

​Endpoint

​Path parameters

​Headers

​Response

​Code examples

​Example response

​Errors

Endpoint

Path parameters

Headers

Response

Code examples

Example response

Errors