Running Batches

Open, close, and reconcile batches using the operations supported by your terminal's processor configuration.

Get started with Koard

Use manual operations where supported, or monitor the managed settlement cycle through batch reads, reports, and webhooks.

What you learn

In this guide, you'll learn:

  • How to choose between Koard-managed and self-managed batch processing
  • Core batch operations: opening, closing, and editing batches
  • Required fields for self-managed batch processing
  • Webhook integration for real-time batch updates
  • Processor-specific considerations and constraints
  • Best practices for batch management and error handling

Before you begin

This guide covers batch processing operations in Koard. For a better understanding of batch concepts, see our Batch and Settlements overview. If you're ready to start processing payments, see our Running Payments guide.

Processor Capabilities

Configuration Manual operations Scheduling
TSYS terminal capture Open, close, and edit supported batches Editable terminal batch schedule
Elavon terminal capture Open, close, and edit supported batches Editable terminal batch schedule
Worldpay Manual close/release of an existing open batch; explicit open is not supported Scheduled release is supported; Worldpay creates batches
Managed Fiserv integration No manual open, close, or edit Automatic fixed cycle; monitor through webhooks and read APIs

Use the selected terminal's supported configuration. The presence of a general batch endpoint does not mean every processor supports that operation. See Fiserv automatic settlement and Automated Batch Scheduling.

Two Batch Processing Approaches

Koard supports two distinct approaches for batch processing based on your technical requirements and business model.

Best for: Tap to Pay terminals with specific gateway configurations

Koard can handle batches entirely for a MID/TID combination. This approach is recommended if you have specific terminals configured on the gateway for Tap to Pay.

Key benefits:

  • Scheduled Management: Koard runs the configured settlement cycle
  • Status Tracking: Automatic transaction status tracking and reconciliation
  • Outcome Details: Batch responses and reports support reconciliation
  • Webhook Integration: Real-time updates for all batch events

Self-Managed Batches

Best for: Enterprise ISVs and PSPs with existing batch infrastructure

If you prefer to manage batches yourself, you'll need to handle the core batch operations and maintain the required transaction data.

Key requirements:

  • Required Fields: Maintain all necessary transaction data
  • Webhook Integration: Process transaction events for batch management
  • Sequential Ordering: Maintain proper batch number sequencing
  • Error Handling: Reconcile the existing batch before deciding whether to retry

Core Batch Operations

Koard provides several core functions that you can apply to batches and transactions:

Operation Description When to Use API Endpoint
List Batches Retrieve paginated list of batches Viewing batch history, filtering by status GET /v1/batches
Download Report Get a temporary download URL for an available managed report Reconciliation GET /v1/batches/{batch_id}/report
Get Batch Retrieve specific batch details View batch status and transactions GET /v1/batches/{batch_id}
Open Batch Create a new batch for transactions Start of business day or when needed POST /v1/batches/open
Close Batch Finalize and submit batch for processing End of business day or when ready POST /v1/batches/{batch_id}/close
Edit Batch Add or remove transactions from open batch Before closing the batch PUT /v1/batches/{batch_id}/edit

Listing Batches

GET /v1/batches?limit=50&offset=0&statuses=open

Query Parameters:

  • account_id (optional): Filter by owning account
  • terminal_id (optional): Filter by terminal ID
  • statuses (optional): Filter by batch lifecycle statuses: accepts multiple values (open, closed, submitted, accepted, partially_accepted, rejected, cancelled)
  • processor_config_id (optional): Filter by processor config ID
  • limit (optional): Maximum items per page (1-500, default: 50)
  • offset (optional): Number of items to skip (default: 0)

Getting a Batch

GET /v1/batches/{batch_id}?include_transactions=true

Query Parameters:

  • include_transactions (optional): If true, embed transactions with the batch (default: false)

Opening a Batch

POST /v1/batches/open
{
  "terminal_id": "tid_987654321",
  "processor_batch_id": "batch_001"
}

Required Fields:

  • terminal_id: The terminal identifier
  • processor_batch_id (optional): Assigned processor batch number override where supported. For TSYS, Koard computes the number (001 through 999) and ignores a supplied override.

Closing a Batch

POST /v1/batches/{batch_id}/close

No request body is required. The batch must be in an open status, and the configuration must support manual close/release. This operation is unavailable for the managed Fiserv integration.

When the close operation returns a Batch object, inspect status, response, and rejection_reason. HTTP 200 alone does not establish acceptance. A final duplicate settlement response can return HTTP 409 with a Batch body, and a non-accepted response can return HTTP 502 with a Batch body. Validation, concurrent submission, and transport failures can return an error envelope instead. Inspect the body and reconcile the existing batch before retrying.

A Worldpay release with an unknown outcome can return HTTP 503 while the batch remains submitted. Preserve that batch and contact support with its ID to reconcile the outcome before another release.

Editing an Open Batch

Only open batches can be edited.

PUT /v1/batches/{batch_id}/edit
{
  /*"added_transactions": ["17279734-fa7b-4f26-a945-19a8a98b6258"],
  "removed_transactions": [],*/
  "processor_batch_id": "6"
}

Body Fields (all optional):

  • processor_batch_id: The processor batch ID
  • added_transactions: List of transaction IDs to add to the batch
  • removed_transactions: List of transaction IDs to remove from the batch

Self-Managed Batch Requirements

If you choose to run batches yourself, you'll need to maintain these essential fields for each transaction:

Required Transaction Fields

Field Description Example
Approval Code Authorization approval code 123456
Response Code Transaction response code 00
Transaction Identifier Unique transaction ID txn_abc123def456
Local Date/Time Transaction timestamp 2024-01-15T14:30:00Z
Amounts Auth, settled, tip, surcharge, cashback {"auth": 1000, "settled": 1000}
ACI/Void/Reversal Indicators Transaction type indicators {"aci": "Y", "void": "N"}

Webhook Integration

Transaction webhooks use operation event names such as transaction.sale and transaction.refund. The request body is the flat Transaction object, with fields such as transaction_id, event_id, transaction_type, status, status_reason, and batch_id. A sale event can describe an approval, decline, or error; inspect the resulting status before including it in settlement totals.

Batch webhooks carry the flat Batch object. The event name is configured through endpoint subscriptions; delivery identifiers and signature metadata are in the svix-* headers. Use Available Events for the exact payloads, and Setting up Webhooks for signature verification and durable delivery handling.

Deliveries can be delayed, repeated, or arrive out of order. Deduplicate deliveries using svix-id, retain transaction and batch identifiers, and retrieve the current batch when reconciling an outcome.

Batch Lifecycle Management

Manual Settlement Outcomes

For supported manual settlement, start with an open batch and inspect the close response:

Outcome Stored batch state Action
Settlement attempt starts Can remain open; Worldpay records submitted before release Wait for the close result and reconcile the existing batch
Settlement accepted accepted; TSYS and Elavon can move directly from open to accepted Reconcile the batch totals and transaction ledger
Definitive settlement rejection Remains open, with failure details in response and, when available, rejection_reason; batch.rejected is emitted Investigate the response and reconcile before another attempt
Unknown Worldpay release outcome Remains submitted; the close request can return HTTP 503 Contact support to reconcile the release before any retry
Duplicate response or other lost/unclear result Inspect the returned body and retrieve the existing batch Establish its outcome before another submission

An event name does not establish the batch's stored status. For example, batch.rejected can carry an open batch. The managed Fiserv cycle records submission and report reconciliation separately; follow Fiserv Automatic Batches and Settlement for that flow.

Automatic Transaction Addition

When a batch is open on a terminal:

  • Captured Transactions: Automatically added to the open batch
  • Refunds: Automatically added to the open batch
  • Real-time Updates: Webhook events provide immediate status updates

Batch Closure Process

  1. Confirm the configuration supports manual close and the batch is open.
  2. Submit the close request once and retain the batch ID and response.
  3. Inspect the response body and the current batch's status, response, and rejection_reason. A definitive rejection retains the open batch and its transaction assignments; an unknown release outcome requires reconciliation.
  4. Follow Error Handling and Recovery before retrying an unsuccessful or uncertain outcome.

Editing Open Batches

You can edit an open batch by:

  • Adding Transactions: Include new transactions before closing
  • Removing Transactions: Remove transactions if needed
  • Constraint: Only open batches can be edited

Processor-Specific Considerations

TSYS Constraints

TSYS has specific batch ID requirements that affect batch management:

Constraint Description Impact
Batch ID Range Numbered batch IDs from 1-999 Limited batch ID availability
Sliding Window 5-day sliding window for reuse Batch IDs can be reused after 5 days
Uniqueness Unique per MID/TID combination Prevents duplicate batch IDs
Error Handling Reusing batch ID results in error Requires proper ID management

Batch ID Management

  • Default Behavior: Koard automatically configures batch IDs
  • Override Option: You can override batch IDs when running your own batches
  • Webhook Integration: Set batch ID via webhook when managing batches yourself
  • Sequential Order: Maintain proper batch number sequencing

Splitting Batches

Not Recommended: Splitting batches is not recommended due to various constraints imposed by processors like TSYS, Fiserv, and Elavon.

Best Practice: Each MID/TID should have one batch per day to avoid potential duplicate batch ID issues.

Error Handling and Recovery

Failed, Rejected, or Uncertain Batches

  1. Retain the existing batch ID and the close response. If the body is a Batch object, inspect its status, response, and rejection_reason. Otherwise handle the typed error envelope and retrieve the existing batch.
  2. Retrieve the current batch, including transactions when needed. Compare it with your ledger and any available processor report. A timeout or missing response does not establish that settlement failed.
  3. Resolve the reported cause before considering another close request. Retry only after confirming the existing batch remains open and the prior attempt was not accepted. A submitted batch or an unknown release outcome must be reconciled before retrying. If its outcome remains unclear, contact support with the batch ID.
  4. Preserve transaction assignments during recovery. Do not automatically move transactions to a new batch, replay payments, or resubmit settlement after a rejection or timeout.

For managed settlement, investigate rejected or partially accepted records through the batch and processor report. Follow the managed cycle's recovery guidance rather than issuing unsupported manual operations.

Monitoring and Alerts

  • Real-time Status: Monitor batch processing status in real-time
  • Error Notifications: Receive alerts for batch failures
  • Webhook Events: Subscribe to batch status change events
  • Dashboard Monitoring: Visual tracking of batch operations

Best Practices

Batch Timing

  • End of Business: Close batches at the end of each business day
  • Peak Hours: Avoid processing batches during peak transaction times
  • Timezone Considerations: Consider your merchant's timezone for batch windows
  • Business Hours: Process batches during business hours for faster support

Error Handling

  • Outcome Recovery: Reconcile the existing batch before any retry
  • Partial Failures: Handle cases where some transactions in a batch fail
  • Monitoring: Set up alerts for batch processing failures
  • Recovery Procedures: Have clear procedures for handling rejected batches

Performance Optimization

  • Batch Size: Optimize batch sizes for your transaction volume
  • Sequential Processing: Maintain proper batch number sequencing
  • Resource Management: Monitor system resources during batch processing
  • Webhook Processing: Ensure reliable webhook event processing

See also

This wraps up the running batches guide. See the links below for related information: