Fiserv Automatic Batches and Settlement

For Koard's supported managed Fiserv integration, batches are managed automatically. Captured sale/capture events and successful refunds are associated with the relevant batch. Authorization-only holds are not captured settlement amounts.

Manual opening, closing, and editing are not supported for this integration. Those requests return HTTP 400. Do not send manual batch operations or change, disable, or remove the managed schedule. Use the read APIs and webhooks to monitor the cycle.

This guide describes the managed Fiserv configuration supplied by Koard. Batch behavior belongs to the selected processor configuration; do not assume every Fiserv configuration has the same capture or scheduling capabilities.

Settlement Cycle

The managed cycle uses America/Los_Angeles time with a 02:00 cutoff and submission tracking at 02:30. Transactions after the cutoff belong to the next cycle. The cycle follows Pacific time, including daylight-saving transitions; do not implement a fixed UTC offset in your integration.

Koard records submission separately from report reconciliation. submitted does not mean the processor has accepted every record or that the merchant has been funded. Empty cycles are canceled without inventing a processor submission or acceptance event.

Subscribe to Batch Webhooks

Configure your endpoint through the webhook portal. Subscribe to:

The HTTP body is a flat Batch object, not an {event, data} wrapper. Delivery identifiers and signature metadata are in the svix-* headers. Subscribe to the relevant event types in the portal, verify signatures, acknowledge quickly, and deduplicate using svix-id. See Available Events.

Example subset of a batch.submitted body:

{
  "id": "YOUR_BATCH_ID",
  "account_id": "YOUR_MERCHANT_ACCOUNT_ID",
  "terminal_id": "YOUR_TERMINAL_ID",
  "processor_name": "fiserv",
  "processor_config_id": "YOUR_PROCESSOR_CONFIG_ID",
  "status": "submitted",
  "captured_amount": 12875,
  "refunded_amount": 2000,
  "transaction_count": 2,
  "processor_batch_id": "YOUR_PROCESSOR_BATCH_ID",
  "closed_at": "2026-10-10T09:00:00Z"
}

Amounts are integer minor currency units. Use id as the Koard batch ID. The processor batch identifier is separate. Webhook deliveries can be delayed or arrive out of order; retrieve the latest batch state rather than assuming the last delivered event is the newest state.

Read Batches and Transactions

Requires batches:read and access to the owning merchant account.

curl 'https://api.uat.koard.com/v1/batches?account_id=YOUR_MERCHANT_ACCOUNT_ID&limit=50&offset=0' \
  -H 'X-Koard-apikey: YOUR_API_KEY'

curl 'https://api.uat.koard.com/v1/batches/YOUR_BATCH_ID?include_transactions=true' \
  -H 'X-Koard-apikey: YOUR_API_KEY'

List responses contain batches, total, limit, offset, and page. Batch details include status, captured/refunded totals, processor identifiers, and any rejection reason. With include_transactions=true, each transaction includes lifecycle history and batch-specific refund attribution. Use batch_refunded_amount for refunds attributed to this batch, rather than treating lifecycle-wide refunded as this batch's total.

Download the Processor Report

curl 'https://api.uat.koard.com/v1/batches/YOUR_BATCH_ID/report' \
  -H 'X-Koard-apikey: YOUR_API_KEY'

When the managed report is archived, the response contains a temporary url and expires_in: 300. Download the report promptly. Do not log or publish the signed URL. A 404 means no managed report is available. Retry with backoff only when the batch is expected to have a managed report and reconciliation is pending. A batch without a managed report will continue to return 404. Report availability does not confirm funding.

Compare the report, batch totals, and your transaction ledger. Flag partial acceptance, rejection, or an unresolved submitted batch for investigation. See Running Batches for other processors.