---
title: "Start the payouts for a batch"
method: POST
path: "/api/v1/payment-batch/{batchId}/withdraw"
tags: ["Payment Batches"]
---

# Start the payouts for a batch

`POST /api/v1/payment-batch/{batchId}/withdraw`

## Request

- Base URL: `https://sandbox.api.afriex.com`
- URL: `https://sandbox.api.afriex.com/api/v1/payment-batch/{batchId}/withdraw`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/afriex/apis/afriex-business-api/docs/api/v1/payment-batch/:batchId/withdraw/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a payout for every recipient in the batch in one call and records the run as a session. The payouts settle asynchronously, so a webhook callback URL must be configured. Requires the `TRANSACTION.WITHDRAW.CREATE` key permission.

Each call is a new run and pays every recipient again. To retry only the payouts that failed, pass the run's `sessionId`. A call made while a run of the same batch is still in progress is refused with `409`. A batch with no recipients is refused with `400`.

## Query parameters

- `sessionId` string

## Response `200`

Per-recipient outcomes, keyed by `recipientId`.

- object
  - `data` PaymentBatchOutcomes
    - `successes` object
    - `errors` object: The reason each failed item failed. The value is an error code (for example `INVALID_BUSINESS_PAYMENT_METHOD_REQUEST`), or `This item could not be processed` when the failure has no code.

## Other responses

- `400`: The request is invalid, the `batchId` in the path is not a valid id (`INVALID_BUSINESS_PAYMENT_BATCH_REQUEST`), or it came from an IP outside the business's whitelist, carried a bad payload signature or named an unsupported `x-api-version`.
- `401`: Missing or invalid API key, or a key without the permission this endpoint requires.
- `404`: No batch with this id belongs to the calling business.
- `409`: A run of this batch is already in progress.
- `500`: Server error.
- `503`: Temporarily unavailable: an upstream service failed or timed out, or the API is momentarily offline. Retry with backoff and honour the Retry-After header when present.

---

[API](https://skmtc.dev/afriex/apis/afriex-business-api.md) - [All operations](https://skmtc.dev/afriex/apis/afriex-business-api/llms.txt) - [OpenAPI document](https://skmtc.dev/afriex/apis/afriex-business-api/revisions/d94198b6c256?raw)