Payout batches

A payout batch pays many of one customer's stored beneficiaries from that customer's balance in a single call. Read this page before you integrate it: the endpoint is deliberately not a "fire and forget" payment call, and two of its behaviours surprise almost everyone.

1. Creating a batch pays nobody. The batch waits in Draft until a Kwiikpay operator approves and executes it. No route on this API advances it, and no webhook tells you when it moved.
2. HTTP 200 does not mean the batch is good. Bad items come back as Skipped, and a batch whose items are all bad is created in status Rejected — with 200 and success: true.

Scopes: payout-batches:read for the two read routes and payout-batches:write for create. These are their own pair — transactions:write does not cover them (see Authentication & scopes).

The three routes

Creating a batch

curl -X POST https://api.kwiikpay.io/api/v1/partner/customers/{customerId}/payout-batches \
  -H "X-Api-Key: kp_live_..." \
  -H "Idempotency-Key: payroll-2026-09-a1b2c3" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "GBP",
    "rail": "FPS",
    "items": [
      { "beneficiary_id": "0198e2f4-6b7c-7d3a-9f1e-2c4a5b6d7e8f", "amount": 12500, "reference": "Salary Sep" },
      { "beneficiary_id": "0198e2f4-6b7c-7d3a-9f1e-2c4a5b6d7e90", "amount": 4000 },
      { "beneficiary_id": "0198e2f4-6b7c-7d3a-9f1e-2c4a5b6d7e91", "amount": 0 }
    ]
  }'

Every item names a beneficiary you have already registered for this customer with POST /api/v1/partner/customers/{customerId}/banking/beneficiaries, in the batch currency, that has finished provisioning at the provider and has been approved. amount is in minor units at a scale of 2 for every currency (12500 is 125.00). rail and reference are optional (see below).

The response for the request above:

{
  "success": true,
  "status_code": 200,
  "message": "Payout batch created successfully",
  "data": {
    "payout_batch": {
      "id": "0198e2f4-...",
      "customer_id": "…",
      "currency": "GBP",
      "rail": "FPS",
      "status": "Draft",
      "item_count": 3,
      "success_count": 0,
      "failure_count": 1,
      "total_amount": 16500,
      "executed_amount": 0,
      "skipped_amount": 0,
      "approved_at": null,
      "completed_at": null,
      "created_at": "2026-09-02T10:00:00+00:00",
      "updated_at": "2026-09-02T10:00:00+00:00",
      "items": [
        { "id": "…", "sequence": 1, "beneficiary_id": "…", "amount": 12500, "reference": "Salary Sep", "status": "Pending", "fiat_payment_id": null, "failure_code": null, "failure_reason": null },
        { "id": "…", "sequence": 2, "beneficiary_id": "…", "amount": 4000, "reference": null, "status": "Pending", "fiat_payment_id": null, "failure_code": null, "failure_reason": null },
        { "id": "…", "sequence": 3, "beneficiary_id": "…", "amount": 0, "reference": null, "status": "Skipped", "fiat_payment_id": null, "failure_code": "validation", "failure_reason": "amount must be a positive whole minor-unit value." }
      ]
    }
  }
}

Read the counters carefully: failure_count: 1 on a brand-new Draft batch means one item was refused at intake — nothing has been paid or failed to pay. total_amount is the payable total: the sum of every non-skipped item. Skipped items are excluded and reported as skipped_amount (total_amount + skipped_amount is what you submitted); executed_amount is the part whose payments have settled. On a batch created before 2026-09-22, executed_amount counts that row's legacy Completed items even where the payment behind one did not settle — the legacy caveat in the item-status table below applies to this total too, and fiat_payment_id remains the per-item authoritative check.

The lifecycle

Draft ──(operator submits)──▶ PendingApproval ──(a different operator approves)──▶ Approved
  │                                  │                                                │
  │ every item skipped               │ operator rejects                               ▼ operator executes
  ▼                                  ▼                                            Executing
Rejected                          Rejected                                            │
                                                                  ┌───────────────────┼───────────────────┐
                                                                  ▼                   ▼                   ▼
                                                              Completed       PartiallyCompleted        Failed

• Your create call produces Draft — or Rejected when every item was skipped.
• No route on this API submits, approves or executes a batch. Those are Kwiikpay operator actions, and approval is four-eyes: the operator who approves must be a different person from the one who created or submitted the batch.
• Execution pays each Pending item, in sequence order, as an ordinary fiat withdrawal from the customer's balance. An item whose payment was created reads Submitted while settlement is open, and the batch settles only when every non-skipped item's money outcome is known: Completed when all payments settled, Failed when none did, PartiallyCompleted for a mix. A batch never reads Completed while its payments are still in flight or under review (2026-09-22).
• There is no webhook for any payout-batch transition. To learn that a batch was approved, executed or rejected, poll GET .../payout-batches/{batchId} and read status.
• There is no turnaround commitment published for operator approval. Ask your Kwiikpay contact how batches are handled for your account before building a flow that depends on timing.

What an item's status means — and what Completed means now

Before 2026-09-22 an item reading Completed only meant "the withdrawal was created" — a payment parked for manual review could sit behind that word while nothing had been paid. That is fixed: Submitted now carries "created, not yet paid", Completed means the money actually settled, and the platform projects every later payment outcome (settlement, failure, a return) onto the item automatically — a batch that held unresolved payments no longer settles, and an item's status is kept in step with the payment behind it. A row created before 2026-09-22 may still show Completed without a settled payment; its fiat_payment_id is the authoritative check.

Failure codes

failure_code is null on Pending, Executing, Submitted and Completed items. Treat the list as open. Nothing that failed is retried automatically: fix the cause and create a new batch for the affected items.

Branch on failure_code, never on failure_reason — the reason is a customer-safe sentence written for display (2026-09-22: provider names and raw error text are never exposed here; the raw text is kept in the audit record for support).

Per-item skipping: what is refused at intake

Each item is checked on its own. A refused item becomes Skipped and the others carry on — the request only fails as a whole for the reasons in the error table at the end.

Because a skipped item can come back with a different amount or a null reference, match response items to your own rows on sequence — the 1-based position in the array you sent — never on amount or reference.

Rails

rail applies to every item. It is validated against the FIAT_REPUBLIC scheme table for the batch currency before anything is stored, and the stored value is the canonical scheme, which is what the response returns. Compare against the canonical value, not against what you sent.

Only the platform currencies (GBP, EUR, USD) reach this table — any other currency is refused at intake with 422 unsupported_currency, before the rail is even looked at.

Case, hyphens and spaces are tolerated. Anything else — including EAGLE_NET_TRANSFER, a provider's internal book transfer — is refused with 422 unsupported_rail. Note that SEPA_INSTANT is accepted only as an alias for SCT: there is no instant SEPA on a batch.

The rail is handed to each beneficiary's provider unchanged at execution. OPENPAYD, which holds some GBP and EUR beneficiaries, accepts FPS and CHAPS but has no case for SCT or BACS. So a EUR batch, or a GBP batch on BACS, whose beneficiary is held at OPENPAYD is refused item by item at execution — after approval — with failure_code: withdrawal_failed. No funds are taken for those items. If your customer's beneficiaries are at OPENPAYD, pay EUR through the single withdrawal route (POST /api/v1/partner/customers/{customerId}/banking/withdrawals), which translates rails per provider; batches do not.

References

The reference is the text the recipient sees on their statement. Omit it (or send null) and the item is paid with "Batch payout". When you do send one it is checked at intake against the stored rail:

Two limits always apply: an empty or blank string is refused wherever a check runs, and a reference over 256 characters (after trimming) is refused on every rail. Kwiikpay does not re-check an unchecked reference before submission — for BACS the provider is the only authority, and its refusal would surface as a Failed item after approval.

Currency

currency must be a platform fiat currency — GBP, EUR or USD — and is matched against each beneficiary's own currency. This route applies the same platform-currency gate as the single withdrawal and beneficiary routes: anything else, AUD included, is refused with 422 unsupported_currency and no batch is created. (Before 2026-09-02 a non-platform currency such as AUD could pass intake on the strength of the FIAT_REPUBLIC scheme table and then reject every item; that trap is closed.)

Size limit

A batch holds 1 to 500 items. Zero items is 422 items_required; more than 500 is 422 too_many_items. Split larger runs into several batches, each with its own Idempotency-Key.

Idempotency on this route

Idempotency-Key is required. What a retry returns depends on when you send it:

• Within 24 hours, identical request: the original response is replayed byte for byte — same body, same message "Payout batch created successfully". The endpoint does not run again.
• Within 24 hours, different body, path or caller: 409 idempotency_key_reused. If the first attempt is still running you get 409 idempotency_key_in_progress instead — retry the identical request shortly.
• After 24 hours, identical request: the endpoint runs again, finds the batch by key and returns it in its current state, with the message "Payout batch retrieved successfully". That message is the only signal that this call did not create the batch — there is no 201 and no header.

Use one key per batch you intend to create, derived from something inherent to the run (a payroll id, a file hash), and keep it with your record of the batch. The general rules are in Idempotency.

Duplicates and exact repeats

Two protections sit on top of the idempotency rules above. Both compare the exact tuple beneficiary + amount + reference (plus, across requests, the customer, currency, rail and transparency).

• Within one request: a row that repeats an earlier row is still paid, and its id is listed in the response's payout_batch.duplicate_item_ids. Null or empty means no repeats. Review the list before approving; it exists so a duplicated CSV line is visible, not silent.
• Across requests: the platform fingerprints each batch's payout set. Creating an identical set again within 7 days under a fresh Idempotency-Key returns 409 duplicate_batch naming the existing batch, its status and creation time. To repeat deliberately — a payroll rerun — resend the identical payout set with "confirm_duplicate": true and a new Idempotency-Key. Without that flag the repeat is refused, so re-uploading the same file cannot pay everyone twice.
• A key reused with a different payout set is refused: you see the idempotency layer's 409 idempotency_key_reused inside its 24-hour window, and the batch layer's 409 idempotency_key_conflict when the same key reaches a batch that already carries a different payout set. Retrieve the original batch; use a new key for a new set.

Listing and reading batches

GET /api/v1/partner/customers/{customerId}/payout-batches returns the customer's batches newest first (created_at, then id, descending) with items set to null on every entry. limit is clamped to 1..500 (default 100; 0 or a negative value becomes 1) and page is 1-based. pagination.total is the real number of batches for the customer and pagination.last_page is ceil(total / per_page) — a customer with 150 batches and the default limit needs two pages. There is no status or date filter.

GET /api/v1/partner/customers/{customerId}/payout-batches/{batchId} returns one batch with its items in sequence order. Poll it to observe transitions.

Both read routes can return two different 404s, both as a flat error object:

Counters, in one worked example

Three items are sent; item 3 has amount 0.

• item_count counts every item, skipped ones included.
• success_count counts items in Completed only — payments that SETTLED. Before execution it is 0; after execution it rises as payments settle, so a partial count means money is still in flight.
• failure_count counts Failed, Returned and Skipped together — everything that did not pay.
• total_amount is the payable total: every non-skipped item's amount. skipped_amount reports the skipped part (total_amount + skipped_amount = what you submitted), and executed_amount is the settled part — the amount that actually left the account in the last row (12500).

Errors by route

POST .../payout-batches

GET .../payout-batches and `GET .../payout-batches/