Payouts

Payouts (disbursements) pay many recipients by bank transfer in one request. You send a batch of ZAR payouts, each with the recipient's bank details, amount and reference; VALR charges the batch fee and pays each recipient from your business's payout account. Recipients are saved as beneficiaries, so you can manage and reuse their details.

How a payout batch works

1. Look up banks. List supported banks gives the code to send for each recipient's bank.
2. Check the cost. Quote fees for withdrawals returns the fee and requiredTotal, the available balance your payout account needs for the payouts plus the fee. Compare it with the PAYOUT balance from Get payments account balances.
3. Create the batch with Create a disbursement batch. A batch created with an API key is executed straight away: there's no separate approval step, the fee is charged and the payouts are submitted.
4. Track it. Get the batch for its status and totals, and list its withdrawals for each payout's status. Pass updatedSince to fetch only the payouts that changed since you last checked.
5. Reconcile. List payout account transactions shows each payout debit, each funding credit, and a credit for any payout the bank returned.

Talk to your VALR account manager about how your payout account is funded.

Safe retries

The X-VALR-Idempotency-Key header is optional, but without it every request creates a new batch. Send a new key with each batch. If a request times out or you aren't sure it arrived, send it again with the same key: you get the original batch's ID back with status 200 instead of a second batch.

Beneficiaries

Beneficiaries are the recipients you pay. Every recipient in a batch is saved as one automatically, and you can also create, update and archive them yourself, one at a time or in bulk. Each bank and account number belongs to one beneficiary: saving an archived recipient again restores it with its original ID.

Before you start

• API key: the DISBURSEMENTS_WRITE bundle manages beneficiaries and creates batches. Because API-key batches execute immediately, it includes the DISBURSEMENTS_APPROVE permission. PAYMENTS_READ reads batches, beneficiaries and balances without changing anything.
• Account: payouts work on your business as a whole. Call these endpoints without X-VALR-SUB-ACCOUNT-ID, with a key that isn't limited to specific sub-accounts; otherwise they return 401 with code -93.
• Formats: amounts in responses are decimal strings, and batch and payout times are ISO 8601 date-times. Paged lists return items, total, limit and offset; page through them with limit and offset.

Endpoints

Disbursements

Batches of payouts to beneficiaries.

Endpoint	Request	Needs
Get a disbursement batch	GET /v2/payments/bulk-withdrawals/batches/{id}	DISBURSEMENTS_READ
List supported banks	GET /v2/payments/bulk-withdrawals/banks	DISBURSEMENTS_READ
List disbursement batches	GET /v2/payments/bulk-withdrawals/batches	DISBURSEMENTS_READ
Create a disbursement batch	POST /v2/payments/bulk-withdrawals/batches	DISBURSEMENTS_CREATE and DISBURSEMENTS_APPROVE
Cancel a disbursement batch	POST /v2/payments/bulk-withdrawals/batches/{id}/cancel	DISBURSEMENTS_UPDATE
Get a batch's fee quote	GET /v2/payments/bulk-withdrawals/batches/{id}/fee-quote	DISBURSEMENTS_READ
Rename a disbursement batch	PUT /v2/payments/bulk-withdrawals/batches/{id}/label	DISBURSEMENTS_UPDATE
List a batch's withdrawals	GET /v2/payments/bulk-withdrawals/batches/{id}/withdrawals	DISBURSEMENTS_READ
Quote fees for withdrawals	POST /v2/payments/bulk-withdrawals/fee-quote	DISBURSEMENTS_READ
List withdrawals	GET /v2/payments/bulk-withdrawals/withdrawals	DISBURSEMENTS_READ
List payout account transactions	GET /v2/payments/payout/history	DISBURSEMENTS_READ
Get a payout account transaction	GET /v2/payments/payout/history/{id}	DISBURSEMENTS_READ

Beneficiaries

Recipients you pay out to. Recipients in each disbursement batch are also saved as beneficiaries automatically.

Endpoint	Request	Needs
List beneficiaries	GET /v2/payments/bulk-withdrawals/beneficiaries	DISBURSEMENTS_READ
Create a beneficiary	POST /v2/payments/bulk-withdrawals/beneficiaries	DISBURSEMENTS_CREATE
Archive a beneficiary	DELETE /v2/payments/bulk-withdrawals/beneficiaries/{id}	DISBURSEMENTS_DELETE
Get a beneficiary	GET /v2/payments/bulk-withdrawals/beneficiaries/{id}	DISBURSEMENTS_READ
Update a beneficiary	PUT /v2/payments/bulk-withdrawals/beneficiaries/{id}	DISBURSEMENTS_UPDATE
Create beneficiaries in bulk	POST /v2/payments/bulk-withdrawals/beneficiaries/bulk	DISBURSEMENTS_CREATE

Payments balances

Balances of your business's payments accounts: payouts, collections, funding and amounts on hold.

Endpoint	Request	Needs
Get payments account balances	GET /v2/payments/account/balances/{type}	PAYMENTS_BALANCES_READ