Batches

Batches

POST /api/v1/batches requires payouts:write and a body containing reference and a payouts list of 1 to 500 payout request objects. Each item has its own unique vendor reference. The batch reference is the batch idempotency key. An identical replay returns the existing batch; changed details conflict.

Validation and reservation are atomic: one invalid row or insufficient prefund rejects the whole request with nothing newly reserved. A successful response is 202 with the batch and items. This confirms queueing, not provider acceptance or payment. Provider outcomes are independent, so a batch can partially succeed. Read item statuses through GET /api/v1/batches/{reference} or the payout lookup. The total_amount and total_fee remain the original batch totals.

Batch status is processing, completed, completed_with_failures, needs_review or cancelled. completed means every item is paid; completed_with_failures means all items are paid, failed or cancelled, with at least one failure or cancellation. A review or reversal can leave the batch in needs_review. Use each item's status for customer accounting.

Request example

{
    "reference": "batch-2026-001",
    "payouts": [
        {
            "reference": "WD-VOUCHER-000123",
            "amount": "100.00",
            "currency": "ZAR",
            "method": "voucher_1voucher",
            "recipient": {
                "first_name": "Alex",
                "surname": "Example",
                "phone": "27821234567",
                "id_type": "Passport",
                "id_number": "EXAMPLE123",
                "country_of_issue": "ZW",
                "nationality": "ZW"
            },
            "metadata": {
                "withdrawal_id": "123"
            }
        }
    ]
}

Requires payouts:write. Each item carries its own unique vendor reference. Replaying an identical batch reference returns the existing batch; changed details produce REFERENCE_CONFLICT.

GET /api/v1/batches/{reference}

Requires payouts:read. Returns the batch and its items. Poll individual item statuses; only paid completes a withdrawal.

Download the dashboard CSV template. The API accepts JSON.

BatchRequest fields

Field	Type	Required	Details
reference	string	Yes	Pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$
payouts	array	Yes	Minimum items: 1; Maximum items: 500

Batch fields

Field	Type	Required	Details
id	string	Yes
reference	string	Yes
status	string	Yes	processing, completed, completed_with_failures, needs_review, cancelled
total_amount	string	Yes	Pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$
total_fee	string	Yes	Pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$
item_count	integer	Yes
payouts	array	Yes
created_at	string	Yes	Format: date-time
currency	string	Yes	ZAR