Manual Batch Close

A Batch groups captured card transactions that will be submitted together for settlement. By default, Paydude closes each open batch automatically once per day. Manual Batch Close lets an enrolled merchant trigger that close on demand — for example, at the end of a shift or a business day — instead of waiting for the automatic close.

Batch Lifecycle

Once a batch is closed (or is closing), a new open batch is created automatically for subsequent captures.

How captures reach a Batch

Whenever a ChargeAPI is captured on an enrolled merchant Account — regardless of how the underlying Payment IntentAPI was created or confirmed — it is added to that merchant’s currently open BatchAPI. No changes are required to how you collect payments.

For a full walkthrough of collecting an online payment, see Online Payments.

Retrieve a Batch

To look up a single batch by its id, call Get a BatchAPI.

curl -L 'https://api.sandbox-paymentsonline.io/v1/batches/{{BATCH_ID}}' \
    -H 'payments-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'payments-api-key: {{SECRET_KEY}}'

Sample response:

{
  "id": "bch_01HXYZGHI...",
  "account_id": "acct_...",
  "status": "closed",
  "opened_at": "2026-07-15T13:00:00.000Z",
  "close_requested_at": "2026-07-15T18:30:00.000Z",
  "closed_at": "2026-07-15T18:30:03.000Z",
  "cutoff_at": "2026-07-15T23:59:59.000Z"
}

A 404 response indicates the batch either does not exist or does not belong to the merchant Account identified by the request headers.

List Batches

Retrieve the current set of batches for a merchant with List BatchesAPI.

curl -L 'https://api.sandbox-paymentsonline.io/v1/batches?status=open' \
    -H 'payments-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'payments-api-key: {{SECRET_KEY}}'

Sample response:

{
  "items": [
    {
      "id": "bch_01HXYZGHI...",
      "account_id": "acct_...",
      "status": "open",
      "opened_at": "2026-07-15T13:00:00.000Z",
      "cutoff_at": "2026-07-15T23:59:59.000Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 30
}

Filter parameters

Close open Batches

To close every open batch for a merchant, call Close open BatchesAPI. The endpoint accepts no body and returns the batches that were transitioned into closing. Repeat calls with no additional open or failed batches return the current state without side effects.

curl -X POST -L 'https://api.sandbox-paymentsonline.io/v1/batches/close' \
    -H 'payments-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'payments-api-key: {{SECRET_KEY}}'

Sample response:

[
  {
    "id": "bch_01HXYZGHI...",
    "account_id": "acct_...",
    "status": "closing",
    "opened_at": "2026-07-15T13:00:00.000Z",
    "close_requested_at": "2026-07-15T18:30:00.000Z",
    "cutoff_at": "2026-07-15T23:59:59.000Z"
  }
]

Close a Batch by ID

To close a single batch — for example, to retry a batch that previously ended in failed — call Close a BatchAPI with the batch id in the URL. The endpoint accepts no body and returns the updated batch.

curl -X POST -L 'https://api.sandbox-paymentsonline.io/v1/batches/{{BATCH_ID}}/close' \
    -H 'payments-account: {{MERCHANT_ACCOUNT_ID}}' \
    -H 'payments-api-key: {{SECRET_KEY}}'

Sample response:

{
  "id": "bch_01HXYZGHI...",
  "account_id": "acct_...",
  "status": "closing",
  "opened_at": "2026-07-15T13:00:00.000Z",
  "close_requested_at": "2026-07-15T18:30:00.000Z",
  "cutoff_at": "2026-07-15T23:59:59.000Z"
}

The endpoint is idempotent on the batch id: repeat calls against a batch already in closing or closed return the current state without side effects. A call against a failed batch resets the failure and retries the close.

Webhook Events

Subscribe to these WebhookAPI events to be notified as a batch progresses through its lifecycle:

Each event’s data field contains the current BatchAPI object.