Batches

Batches

POST /api/v1/batches with { "reference": "...", "payouts": [ <payout objects> ] } (max 500). Validated and reserved atomically — one bad row rejects the whole batch with nothing reserved. Returns 202 with the batch; items are submitted individually in the background (the provider has no bulk API). Batch status: processing, completed, completed_with_failures, needs_review, cancelled.

Request example

{
    "reference": "batch-2026-001",
    "payouts": [
        {
            "reference": "WD-2026-000123",
            "amount": "100.00",
            "currency": "ZAR",
            "method": "standard_bank_instant_money",
            "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/

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
reference	string	Yes
payouts	array	Yes

Batch fields

Field	Type	Values
id	string	—
reference	string	—
status	string	processing, completed, completed_with_failures, needs_review, cancelled
total_amount	string	—
total_fee	string	—
item_count	integer	—
payouts	array	—
created_at	string	—
currency	string	ZAR