List withdrawals

GET

/v2/payments/bulk-withdrawals/withdrawals

Requires DISBURSEMENTS_READ, granted by PAYMENTS_READ or DISBURSEMENTS_WRITE (bundles)

Returns withdrawals across all your batches, newest first, each with a summary of its batch.

Parameters

Query Parameters

status

Only withdrawals with this status.

Type

string

Valid values

"PENDING""APPROVED""EXECUTING""SUBMITTED""PROCESSING""PAID""FAILED""SKIPPED"

Example"FAILED"

failureCode

Only failed withdrawals with this failure category.

Type

string

Valid values

"GENERIC""INSUFFICIENT_FUNDS""INVALID_DETAILS""NO_BANK_ACCOUNT""AMOUNT_TOO_SMALL""ACCOUNT_UNVERIFIED""SYSTEM_UNAVAILABLE""DECLINED""REVERSED""NO_PAYOUT_RESULT""INVALID_REFERENCE"

Example"INSUFFICIENT_FUNDS"

beneficiaryId

Only withdrawals to this beneficiary.

Type

string

Example"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"

Format

"uuid"

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": "c4e8a2b6-3d5f-4a1c-9e7b-2f4d6a8c0e1b",

"amount": "12500.75",

"bank": "FNB",

"bankDisplayName": "FNB/RMB",

"accountType": "CHEQUE",

"accountHolder": "Thandi Nkosi",

"accountNumberMasked": "*******0327",

"accountNumber": "62845190327",

"branchCode": "250655",

"reference": "OCT SALARY",

"linkedBankAccountId": null,

"withdrawalId": "0f3b5d7e-9a1c-4e2f-8b4d-6c8e0a2b4d6f",

"status": "PAID",

"failureReason": null,

"failureReasonCode": null,

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

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

"batch": {

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

"label": "October salaries",

"status": "COMPLETED",

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

"uploadedByName": null,

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

"approvedByName": 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.