Create a disbursement batch

POST

/v2/payments/bulk-withdrawals/batches

Requires DISBURSEMENTS_CREATE (granted by DISBURSEMENTS_WRITE) and DISBURSEMENTS_APPROVE (granted by DISBURSEMENTS_WRITE) (bundles)

Creates a batch of ZAR payouts and executes it straight away: batches created with an API key skip the approval step, so the fee is charged and the payouts are submitted immediately, and the key needs the DISBURSEMENTS_APPROVE permission as well (the DISBURSEMENTS_WRITE bundle includes it). Your payout account must have enough available balance for the payouts plus the fee. X-VALR-Idempotency-Key is optional. Send one to make retries safe: repeating a key returns the original batch's ID with status 200. Without it, every request creates a new batch.

Parameters

Header Parameters

X-VALR-Idempotency-Key

Your unique key for this batch: up to 128 letters, digits, :, _, . or -. Reuse it only to retry the same request.

Type

string

Example"payroll-2026-10-23-001"

Pattern

"^[A-Za-z0-9:_.\\-]{1,128}$"

Max Length

128

Request Body

application/json

{

"label": "October salaries",

"withdrawals": [

{

"bank": "FNB",

"accountHolder": "Thandi Nkosi",

"accountNumber": "62845190327",

"branchCode": "250655",

"accountType": "CHEQUE",

"amount": 12500.75,

"reference": "OCT SALARY",

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

"type": "INDIVIDUAL",

"country": "ZA"

},

{

"bank": "CAPITEC",

"accountHolder": "Sipho Dlamini",

"accountNumber": "1453987621",

"branchCode": "470010",

"accountType": "SAVINGS",

"amount": 8000.25,

"reference": "OCT SALARY"

}

]

}

Responses

A batch with this idempotency key already exists. Its ID is returned and nothing new is created.

Content-Type

application/json

{

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

}

Samples

Errors

HTTP	Error	When
400	-113INVALID_JSON	The body isn't valid JSON.
400	-11INVALID_REQUEST	The body is empty or has no withdrawals array, or X-VALR-Idempotency-Key isn't valid, in which case validationErrors names the header.
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	The idempotency key belongs to a batch that was cancelled, so retry with a new key, or to one that failed after its fee was charged, so contact support instead of retrying.
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.