Appearance
Create beneficiaries in bulk​
POST
/v2/payments/bulk-withdrawals/beneficiaries/bulk
Requires DISBURSEMENTS_CREATE, granted by DISBURSEMENTS_WRITE (bundles)
Saves a list of beneficiaries in one all-or-nothing request and returns them in the order sent. A beneficiary with the same bank and account number as an existing one updates it, restoring it if archived, instead of failing.
Request Body​
application/json
JSON
{
"beneficiaries": [
{
"bank": "FNB",
"accountHolder": "Thandi Nkosi",
"accountNumber": "62845190327",
"branchCode": "250655",
"accountType": "CHEQUE",
"type": "INDIVIDUAL",
"email": "thandi@example.com",
"reference": "SALARY",
"country": "ZA"
},
{
"bank": "STANDARD",
"accountHolder": "Karoo Fresh Produce (Pty) Ltd",
"accountNumber": "271934058",
"branchCode": "051001",
"accountType": "CHEQUE",
"type": "BUSINESS",
"tradingName": "Karoo Fresh",
"email": "accounts@example.com",
"country": "ZA"
}
]
}
Responses​
OK
application/json
JSON
[
{
"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-23T10:20:15.380Z",
"lastPaidAt": null,
"deletedAt": null,
"deletedBy": null
},
{
"id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
"bank": "STANDARD",
"bankDisplayName": "Standard Bank",
"accountHolder": "Karoo Fresh Produce (Pty) Ltd",
"accountNumberMasked": "*****4058",
"accountNumber": "271934058",
"branchCode": "051001",
"accountType": "CHEQUE",
"email": "accounts@example.com",
"type": "BUSINESS",
"tradingName": "Karoo Fresh",
"reference": null,
"country": "ZA",
"createdAt": "2026-10-23T10:20:15.380Z",
"updatedAt": "2026-10-23T10:20:15.380Z",
"lastPaidAt": null,
"deletedAt": null,
"deletedBy": null
}
]
Samples​
Errors
| HTTP | Error | When |
|---|---|---|
| 400 | -113INVALID_JSON | The body isn't valid JSON. |
| 400 | -11INVALID_REQUEST | The body is empty or a field fails validation; validationErrors lists each failing field. |
| 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.