Appearance
Create a beneficiary​
POST
/v2/payments/bulk-withdrawals/beneficiaries
Requires DISBURSEMENTS_CREATE, granted by DISBURSEMENTS_WRITE (bundles)
Saves a beneficiary you can pay out to. If an archived beneficiary has the same bank and account number, it's restored with these details and keeps its original ID.
Request Body​
application/json
JSON
{
"bank": "FNB",
"accountHolder": "Thandi Nkosi",
"accountNumber": "62845190327",
"branchCode": "250655",
"accountType": "CHEQUE",
"type": "INDIVIDUAL",
"email": "thandi@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": "CHEQUE",
"email": "thandi@example.com",
"type": "INDIVIDUAL",
"tradingName": null,
"reference": "SALARY",
"country": "ZA",
"createdAt": "2026-09-01T10:12:30.004Z",
"updatedAt": "2026-09-01T10:12:30.004Z",
"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. |
| 409 | CONFLICT | An active beneficiary with this bank and account number already exists; update it instead. |
| 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.