Batches

A batch is a container for payments. It has no status of its own. It gives its payments their defaults, lets you restrict how they are paid, and lets you submit them all with one call. A typical batch is one payroll run, one tournament, or one month of invoices.

Before you start

• Creating and editing batches needs the Write permission. Submitting a batch needs the Payment Approval permission. See Permissions.
• Know which payment category your payments fall under. The category drives tax treatment; see the Tax Guide.

Step 1: Create a batch

curl -X POST https://api-sandbox.paymentlabs.io/batches \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October creator payouts",
    "referenceId": "payrun-2026-10",
    "defaultPaymentCategory": "royalties",
    "taxJurisdiction": "us"
  }'

Create Batch returns 201 with the batch and a Location header. Keep the id (B-...).

Creating a batch fires the batch-created webhook.

Step 2: Add payments

Add payments one by one with Create Payment (see Creating and Submitting Payments), or many at once from a spreadsheet with a payment import.

The batch's totals (totalAmount, numberOfPayments, paymentsSummary and the rest) are recalculated in the background. They can lag a few seconds behind the payments you just added.

Step 3: Submit the batch

Submit Batch queues every payment in the batch that can be sent, and returns 202 Accepted.

curl -X POST https://api-sandbox.paymentlabs.io/batches/B-01JDA1B2C3D4E5F6G7H8J9K0M1/submit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "autoSubmit": true, "feeCap": "5.00", "fxDifferenceCoverage": "payor" }'

Which payments a batch submit sends:

• Only payments in DRAFT, FAILED or RETURNED.
• Only when the payee is payable, or when autoSubmit is true.
• Never a payment that is being cancelled.

Repeating Submit Batch does not send a payment twice: a payment picked up by two requests is sent only once.

Every other payment is skipped without an error, so a 202 does not tell you how many payments were sent. Follow each payment through the payment-status-changed webhook, or search the batch's payments after a few seconds. A batch submit does not check your ledger balance first: payments that the balance cannot cover wait for funds (see Funding and Ledger Accounts).

To submit selected payments instead of the whole batch, submit each payment on its own (see Creating and Submitting Payments).

Update, archive and find batches

• Read one batch: Get Batch.
• List batches: List Batches returns your active batches, oldest first. Send archived=true to list only archived batches instead. When the response has nextPage, pass it as exclusiveStartId to get the next page. To filter or sort, use Search Batches.
• Search batches: Search Batches. You can filter and sort on id, referenceId, name, taxJurisdiction, defaultPaymentCategory, archived, auditInfo.createdAt, auditInfo.updatedAt, auditInfo.createdBy and auditInfo.updatedBy. See Search, Exports and Pagination.
• Update a batch: Patch Batch with any of name, referenceId, defaultPaymentCategory, allowedPaymentMethods, deniedCountries and archived. It returns 204 and fires batch-changed.
  • A new defaultPaymentCategory applies to payments you create afterwards. Add "updateExistingPayments": true to also re-categorize the batch's DRAFT payments.
  • Changes to name, allowedPaymentMethods, deniedCountries and archived are copied to the batch's payments in the background. A new deniedCountries list moves unsent payments of affected payees into or out of RESTRICTED.
• Archive a batch: PATCH with "archived": true. An archived batch is read-only: you cannot add payments to it, edit it, or submit it. To use it again, PATCH with "archived": false. If a payment in an archived batch is returned, Payment Labs unarchives the batch so you can send the payment again.

To stop every unsent payment in a batch, cancel them with Cancel Batch Payments. It returns 204 and cancels, in the background, each payment that is DRAFT, FAILED, RETURNED, WAITING_PAYABILITY or RESTRICTED and is not already queued for sending.

Errors and edge cases

Next steps

• Creating and Submitting Payments
• Payment Imports
• Payment Statuses