List disbursement batches

GET

/v2/payments/bulk-withdrawals/batches

Requires DISBURSEMENTS_READ, granted by PAYMENTS_READ or DISBURSEMENTS_WRITE (bundles)

Returns your disbursement batches, newest first, a page at a time.

Parameters

Query Parameters

status

Only batches with this status.

Type

string

Valid values

"PENDING_APPROVAL""APPROVED""PROCESSING""COMPLETED""PARTIALLY_COMPLETED""FAILED""CANCELLED"

Example"PROCESSING"

limit

Page size, from 1 to 200; values outside that range are clamped.

Type

integer

Default

50

offset

Number of items to skip.

Type

integer

Default

0

Responses

OK

Content-Type

application/json

{

"items": [

{

"id": "5b9a3c1e-2f4d-4a7b-9c8e-1d2f3a4b5c6d",

"label": "October salaries",

"currency": "ZAR",

"totalAmount": "20501.00",

"withdrawalCount": 2,

"status": "COMPLETED",

"uploadedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",

"uploadedByName": null,

"approvedBy": "8d2f4e6a-1b3c-4d5e-8f9a-0b1c2d3e4f5a",

"approvedByName": null,

"approvedAt": "2026-10-23T08:15:02.481Z",

"createdAt": "2026-10-23T08:15:01.912Z",

"updatedAt": "2026-10-23T09:02:44.118Z",

"completedAt": "2026-10-23T09:02:44.118Z",

"feeQuote": null

}

],

"total": 1,

"limit": 50,

"offset": 0,

"truncated": null

}

Samples

Errors

HTTP	Error	When
400	BAD_REQUEST	A query parameter or field is invalid.
403	-16098PAYMENTS_USER_ACCESS_NOT_CONFIGURED	Payments haven't been set up for your business yet.
500	INTERNAL_ERROR	Unexpected error in the payments service.
502	-16097EXCHANGE_API_ERROR	The payments service failed to process the request.
502	EXCHANGE_API_ERROR	The payments service couldn't complete the request. Try again later.
503	-16099PAYMENTS_BACKEND_PROXY_DISABLED	Payments endpoints are temporarily unavailable.

Plus the errors common to all signed endpoints.