Process a bulk transfer

Batches are not processed automatically the moment you create them. After creating a bulk transfer, call this endpoint with the bulkTransferId to start execution. It queues every item still in pending status for background processing and returns immediately.

This endpoint is safe to call more than once for the same batch. Only the first call actually claims the batch and enqueues it; any call that arrives while the batch is already processing is a no-op — it returns 200 rather than queuing a second time (see Response below). Once the batch is completed, further calls are rejected outright. Use Reprocess to retry failed items instead — this endpoint never touches items that aren’t pending.

Endpoint

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

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. The batch must belong to this business and to the client identified by your API key — see the ownership note under Errors below.

Request body

string

required

The ID of the batch to process, returned by Create a bulk transfer.

Response

There are two possible successful outcomes, distinguished by HTTP status:

Queued (first call)

boolean

true.

string

"Bulk transfer queued for processing".

string

The batch that was queued.

string

Internal identifier for the background processing job. Not required for polling — use Get a bulk transfer to track progress instead.

Before queuing, this endpoint checks that your business account has enough available balance to cover the sum of all currently-pending items. If it doesn’t, nothing is queued and the request fails — see Errors below. If the check passes, the batch’s status flips to processing immediately, and this response returns 202.

Already in progress (duplicate call)

boolean

true.

string

"Bulk transfer is already being processed".

string

The batch you asked to process.

If the batch is already processing at the moment this request arrives — for example, a retried request, or a genuinely concurrent call — nothing is re-queued and no balance check runs again. This response returns 200, and data has no jobId since no new job was created.

Code examples

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

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

import requests

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

Example responses

202 — first call, newly queued:

{
  "status": true,
  "message": "Bulk transfer queued for processing",
  "data": {
    "bulkTransferId": "6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f",
    "jobId": "42"
  }
}

200 — duplicate call, already in progress:

{
  "status": true,
  "message": "Bulk transfer is already being processed",
  "data": {
    "bulkTransferId": "6f9d3e2a-1b4c-4a8d-9e2f-3c1a2b4d5e6f"
  }
}

Errors

Status	Cause
`400 Bad Request`	`businessId` header missing (`"businessId is required in headers"`)
`400 Bad Request`	`bulkTransferId` missing or not a valid UUID
`400 Bad Request`	`"Bulk transfer is already completed"`
`400 Bad Request`	`"No payment account for this business"`
`400 Bad Request`	`"Insufficient Funds"` — your account can’t cover the total of all pending items
`401 Unauthorized`	Credentials missing or invalid
`404 Not Found`	No bulk transfer with this ID exists for your client and business

The batch is looked up scoped to your API key’s client and the businessId you send, the same as Get a bulk transfer and Reprocess — a bulkTransferId that exists but belongs to a different business returns 404, not the batch.

If the request fails for any reason after the batch has been claimed ("No payment account for this business", "Insufficient Funds", or an unexpected error), the batch’s status is set to failed with failureReason set to the error message, rather than being left stuck in processing. Check Get a bulk transfer for failureReason if a batch ends up failed without any items ever having started.

See Errors for the full envelope and error code reference.

Overview

Members

Business

Virtual accounts

Funds

Bulk transfers

Disputes

Subscriptions

Payouts

Audit logs

Settings

Process a bulk transfer

Endpoint

Headers

Request body

Response

Queued (first call)

Already in progress (duplicate call)

Code examples

Example responses

Errors

​Endpoint

​Headers

​Request body

​Response

​Queued (first call)

​Already in progress (duplicate call)

​Code examples

​Example responses

​Errors

Endpoint

Headers

Request body

Response

Queued (first call)

Already in progress (duplicate call)

Code examples

Example responses

Errors