Payment Batch

A Payment Batch groups multiple payment instructions into a single unit for processing. Batches provide rate-limited execution, atomic status tracking, and a single digest notification on completion — making them ideal for high-volume payment scenarios like payroll or vendor disbursements.

Payment Batch Object

{
  "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50QmF0Y2gvMQ",
  "status": "completed",
  "label": "January 2026 Payroll",
  "idempotency_key": "payroll-2026-01",
  "total_count": 50,
  "succeeded_count": 49,
  "failed_count": 1,
  "metadata": {
    "department": "engineering",
    "period": "2026-01"
  },
  "submitted_at": "2026-01-15T11:00:00.000Z",
  "completed_at": "2026-01-15T11:05:30.000Z",
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-01-15T11:05:30.000Z"
}

Attributes

Attribute	Type	Description
id	string	Unique identifier for the payment batch
status	string	Current status of the batch (see Batch Statuses)
label	string	Human-readable label for the batch (e.g., "January Payroll")
idempotency_key	string	Unique key to prevent duplicate batch creation, scoped to company
total_count	integer	Total number of payment instructions in the batch
succeeded_count	integer	Number of payment instructions that completed successfully
failed_count	integer	Number of payment instructions that failed
metadata	object	Arbitrary key-value pairs for your own tracking purposes
submitted_at	string	ISO 8601 timestamp when the batch was submitted for processing
completed_at	string	ISO 8601 timestamp when all payments in the batch finished
created_at	string	ISO 8601 timestamp when the batch was created
updated_at	string	ISO 8601 timestamp when the batch was last updated

Batch Statuses

Payment batches progress through different statuses during their lifecycle:

Status	Description
building	Batch is open for adding payment instructions
processing	Batch has been submitted and payments are being executed
completed	All payments in the batch completed successfully
completed_with_failures	Some payments succeeded and some failed
failed	All payments in the batch failed
expired	Batch was left in building status for more than 7 days

Terminal Statuses

completed, completed_with_failures, failed, and expired are terminal statuses. Batches in these statuses cannot change state.

Batch Lifecycle

building → processing → completed
                      → completed_with_failures
                      → failed

building → expired (after 7 days of inactivity)

1. Building — Create the batch and add payment instructions one at a time via the Create Payment endpoint with a payment_batch_id.
2. Processing — Submit the batch via Process Payment Batch. Payments are executed with rate-limited concurrency to avoid API throttling. Expired quotes are automatically refreshed.
3. Terminal — Once all payments have been processed, the batch transitions to its final status based on results.

Limits

Limit	Value	Description
Maximum payments	500	Maximum number of payment instructions per batch
Minimum payments	1	At least one payment instruction required to process
Building timeout	7 days	Batches in building status expire after 7 days

Idempotency

The idempotency_key parameter prevents duplicate batch creation. If you submit a create request with an idempotency key that already exists for your company:

• The existing batch is returned with a 200 OK status
• No duplicate batch is created
• Idempotency keys are scoped to your company

Notifications

When a batch completes processing, a single digest notification is sent to all workspace users. This replaces the individual per-payment notifications, reducing notification noise for large batches.

Individual payment event notifications (CompletedEvent, FailedEvent, DebitInitiatedEvent) are suppressed for payments that belong to a batch.

Available Operations

• Create Payment Batch — Create a new batch for grouping payments
• Get Payment Batch — Retrieve details and progress of a batch
• List Payment Batches — List all batches with optional filtering
• Process Payment Batch — Submit a batch for processing

For detailed API endpoints and request/response examples, see the Payment Batches API Reference.