List beneficiaries

GET

/v2/payments/bulk-withdrawals/beneficiaries

Requires DISBURSEMENTS_READ, granted by PAYMENTS_READ or DISBURSEMENTS_WRITE (bundles)

Returns your beneficiaries a page at a time, active ones by default. Use query to search by name, trading name, email address or account number.

Parameters

Query Parameters

query

Text to search for in the name, trading name, email address and account number. Results are ranked by relevance and sort is ignored.

Type

string

Example"nkosi"

type

Only beneficiaries of this type. Beneficiaries saved from a batch without a type match neither value. Case-insensitive.

Type

string

Valid values

"INDIVIDUAL""BUSINESS"

Example"INDIVIDUAL"

status

ACTIVE, ARCHIVED or ALL. Case-insensitive.

Type

string

Valid values

"ACTIVE""ARCHIVED""ALL"

Example"ACTIVE"

Default

"ACTIVE"

sort

created (newest first), lastPaid (most recently paid first, never paid last) or archived (most recently archived first). Defaults to archived when status is ARCHIVED, otherwise created; archived needs status ARCHIVED or ALL.

Type

string

Valid values

"created""lastPaid""archived"

Example"lastPaid"

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": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",

"bank": "FNB",

"bankDisplayName": "FNB/RMB",

"accountHolder": "Thandi Nkosi",

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

"accountNumber": "62845190327",

"branchCode": "250655",

"accountType": "CHEQUE",

"email": "thandi@example.com",

"type": "INDIVIDUAL",

"tradingName": null,

"reference": "SALARY",

"country": "ZA",

"createdAt": "2026-09-01T10:12:30.004Z",

"updatedAt": "2026-10-23T08:15:02.010Z",

"lastPaidAt": "2026-10-23T08:15:03.204Z",

"deletedAt": null,

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