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,
      "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 sum of all items, skipped ones included, so it is not the amount that will leave the account.

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, and then settles the batch status: Completed when every non-skipped item completed, Failed when none did, PartiallyCompleted for a mix.
• 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 does not mean

Completed means the withdrawal exists — not that the money has settled. The withdrawal may still be pending at the banking provider or parked for manual review, and the batch item never changes again once it is Completed. To follow the money, take the item's fiat_payment_id and find that id in GET /api/v1/partner/customers/{customerId}/banking/withdrawals; the withdrawal's own status is where settlement and any later failure are reported.

Failure codes

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

Branch on failure_code, never on failure_reason.

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 Fiat Republic's 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, Fiat Republic'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 Fiat Republic's 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.

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, so it is always 0 before execution.
• failure_count counts Failed and Skipped together.
• total_amount never changes: it is the sum of every item's amount as recorded.

The amount that actually left the account in the last row is the sum of the Completed items (12500), which you compute from items — no field on the batch reports it.

Errors by route

POST .../payout-batches

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