Cancel a disbursement batch

POST

/v2/payments/bulk-withdrawals/batches/{id}/cancel

Requires DISBURSEMENTS_UPDATE, granted by DISBURSEMENTS_WRITE (bundles)

Cancels a batch that is pending approval or approved, and marks its withdrawals that haven't been submitted as SKIPPED. Batches created with an API key are executed immediately, so they usually can't be cancelled.

Parameters

Path Parameters

id*

Batch ID.

Type

string

Required

Example"7c1e9a3b-5d2f-4b6a-8e0c-2a4b6c8d0e1f"

Format

"uuid"

Responses

OK

Content-Type

application/json

{

"id": "7c1e9a3b-5d2f-4b6a-8e0c-2a4b6c8d0e1f",

"label": "November rent",

"currency": "ZAR",

"totalAmount": "45000.00",

"withdrawalCount": 3,

"status": "CANCELLED",

"uploadedBy": "2e4a6c8e-0b1d-4f3a-9c5e-7a9b1d3f5a7c",

"uploadedByName": {

"name": "Lerato",

"surname": "Mokoena"

},

"approvedBy": null,

"approvedByName": null,

"approvedAt": null,

"createdAt": "2026-10-22T14:03:11.250Z",

"updatedAt": "2026-10-23T08:40:27.733Z",

"completedAt": null,

"feeQuote": null

}

Samples

Errors

HTTP	Error	When
400	BAD_REQUEST	A query parameter or field is invalid.
400	-11INVALID_REQUEST	The batch ID isn't a valid UUID.
403	-16098PAYMENTS_USER_ACCESS_NOT_CONFIGURED	Payments haven't been set up for your business yet.
404	NOT_FOUND	No batch with this ID exists on your account.
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.