Appearance
Update a beneficiary​
PUT
/v2/payments/bulk-withdrawals/beneficiaries/{id}
Requires DISBURSEMENTS_UPDATE, granted by DISBURSEMENTS_WRITE (bundles)
Replaces every field of an active beneficiary; optional fields you leave out are cleared. Changing the bank or account number fails if another beneficiary, including an archived one, already has them.
Parameters​
Path Parameters
id*
Beneficiary ID.
Type
Requiredstring
Example
"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"Format
"uuid"Request Body​
application/json
JSON
{
"bank": "FNB",
"accountHolder": "Thandi Nkosi",
"accountNumber": "62845190327",
"branchCode": "250655",
"accountType": "SAVINGS",
"type": "INDIVIDUAL",
"email": "thandi.nkosi@example.com",
"reference": "SALARY",
"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": "SAVINGS",
"email": "thandi.nkosi@example.com",
"type": "INDIVIDUAL",
"tradingName": null,
"reference": "SALARY",
"country": "ZA",
"createdAt": "2026-09-01T10:12:30.004Z",
"updatedAt": "2026-10-23T11:05:48.902Z",
"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. |
| 404 | NOT_FOUND | No active beneficiary with this ID exists on your account; archived beneficiaries can't be updated. |
| 409 | CONFLICT | Another beneficiary, active or archived, already has this bank and account number. |
| 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.