Running Batches
Open, close, and reconcile batches using the operations supported by your terminal's processor configuration.
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.
Via Koard (Recommended)
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 accountterminal_id(optional): Filter by terminal IDstatuses(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 IDlimit(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 identifierprocessor_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 IDadded_transactions: List of transaction IDs to add to the batchremoved_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
- Confirm the configuration supports manual close and the batch is
open. - Submit the close request once and retain the batch ID and response.
- Inspect the response body and the current batch's
status,response, andrejection_reason. A definitive rejection retains the open batch and its transaction assignments; an unknown release outcome requires reconciliation. - 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
- Retain the existing batch ID and the close response. If the body is a Batch object, inspect its
status,response, andrejection_reason. Otherwise handle the typed error envelope and retrieve the existing batch. - 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.
- 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
submittedbatch or an unknown release outcome must be reconciled before retrying. If its outcome remains unclear, contact support with the batch ID. - 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:
- Batch and Settlements Overview - High-level batch concepts
- Running Payments - Payment processing fundamentals
- Setting up Webhooks - Webhook configuration
- Available Events - Webhook event reference

