Batches

Maker-checker thresholds

If the batch total exceeds your account’s dual-control threshold, the batch lands in awaiting_approval status. A second team member must approve via the dashboard before dispatch.

Below threshold → batch auto-approves to approved status; rows dispatch immediately.

Live-merchant Owner-only self-approve

On live-approved merchants, only the team member assigned the Owner role can self-approve their own batches even when they hold both payout_bulk_upload and payout_bulk_approve permissions. Other dual-perm roles (Admin, Approver, etc.) drop to maker-checker on live and need a different teammate to approve.

This is a security tightening for real-money flows — non-Owner self-approve still works on sandbox for development velocity. The Owner role is capped at 3 holders per merchant, so the “self-approve surface” stays narrow even when team size grows.

When self-approve is denied, the API returns:

{
  "type": "self_approval_denied",
  "message": "A different teammate must approve this batch on a live merchant. Only the Owner can self-approve on live."
}

Email-OTP gate (dashboard only)

When the merchant has MerchantLimits.otpRequiredAtAmountMinor configured, dashboard batch approvals trigger an email-OTP for the approver before dispatch. ONE OTP unlocks the entire batch (similar to provider-side bulk-OTP UX). Live env defaults to OTP-on; sandbox bypasses unless requirePayoutOtpInSandbox is set.

API-initiated batches do NOT trigger the OTP gate. POST /v1/batches authenticates via Bearer + IP allowlist + Idempotency-Key. The OTP is reserved for the dashboard’s human-clicked surface.

Validation errors

If any row fails validation, the WHOLE batch is rejected — all-or-nothing semantics. Partial success would leave you guessing about which rows landed; this way you fix the bad rows and resubmit the corrected batch with confidence. Nothing is created and no wallet moves until every row passes.

Rejections come in two shapes, and which one you get depends on how far the batch got.

Shape 1 — structural rejection (400, and 404 currency_not_supported). The body or a row is malformed. Validation stops at the first bad row and names its index in message. There is no per-row array — fix the row it names, resubmit, and the next problem (if any) is reported the same way.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_body",
    "message": "items[3].recipient_account_number must be a 10+ digit string."
  }
}

Shape 2 — semantic rejection (422). The body parsed cleanly, so every row is checked and all failing rows are reported together. These carry a per-row array so you can fix the whole batch in one pass:

{
  "error": {
    "type": "invalid_request_error",
    "code": "unknown_bank_code",
    "message": "One or more rows have a bank_code that doesn't match any Bank row.",
    "violations": [
      { "row_index": 4, "field": "recipient_bank_code", "input": "999", "message": "..." },
      { "row_index": 12, "field": "recipient_bank_code", "input": "0000", "message": "..." }
    ]
  }
}

Every error POST /v1/batches can return

Structural — stops at the first offending row, index named in message:

Account and key state — checked before any row is examined:

Semantic — every failing row reported together:

Which rows failed? Validation-time vs. post-acceptance

These are two different questions with two different answers, and it matters which one you’re asking.

Before acceptance (the errors above). Nothing was created. The batch does not exist, no Payout rows exist, and no money moved. The answer lives in the error response — either the row index in message (structural) or the per-row array (semantic).

After acceptance (201). Every row passed validation and became a Payout. From here rows succeed or fail individually at dispatch, and the answer lives on the items endpoint:

GET /v1/batches/{id}/items

Each item carries status plus failure_code and failure_message when it failed. You can filter server-side with ?status=failed. A batch that was accepted and then had rows fail at the rail is not a validation error and will never appear as one.

Accepts cuid OR bat_xxx reference. Returns the Batch object plus per-status counts.

Cursor-paginated list of payouts in the batch.

Returns the same {object: 'list', has_more, data} envelope; each item is a full Payout object.

Cancels the entire batch atomically. All draft and queued rows are cancelled; processing and terminal-status rows are left untouched.