Automated Batch Scheduling
Automated Batch Scheduling
Koard supports automated batch close or release scheduling per terminal for TSYS, Elavon, and Worldpay. TSYS and Elavon support explicit batch opening; Worldpay creates batches through its host-capture flow. The supported Fiserv integration uses a fixed processor-managed cycle.
Supported Processors
| Processor | Supported | Notes |
|---|---|---|
| TSYS | ✅ | Full support. Batch numbers auto-managed (001-999). |
| Elavon | ✅ | Full support via ViaConex TC 920/921/929. |
| Worldpay | ✅ | Scheduled batch release through the settlement interface; explicit open is unavailable. |
| Fiserv managed integration | Automatic, fixed | Koard tracks the processor-managed cycle; customers cannot change the schedule or manually open, close, or edit batches. See Fiserv settlement. |
| Payroc | ❌ | Not supported for automated scheduling. |
How It Works
- Configure a schedule on the terminal via
PUT /v2/terminals/{terminal_id} - Koard's scheduler runs every minute, checking for terminals due for batch close
- When due, Koard closes or releases the current batch. A new batch is opened where the processor supports explicit open; Worldpay manages batch creation.
- If a close fails, Koard retries up to 10 times with backoff
- On persistent failure, a webhook error event is sent
Setting Up a Schedule
Add a batch_schedule field to your terminal update:
PUT /v2/terminals/{terminal_id}
{
"batch_schedule": {
"timezone": "US/Eastern",
"is_active": true,
"schedule": [
{ "day": "MON", "times": ["23:00"] },
{ "day": "TUE", "times": ["23:00"] },
{ "day": "WED", "times": ["23:00"] },
{ "day": "THU", "times": ["23:00"] },
{ "day": "FRI", "times": ["23:00"] },
{ "day": "SAT", "times": ["23:00"] }
]
}
}
Response
The terminal response includes confirmation that the schedule was saved:
{
"terminal_id": "term-abc123",
"name": "Front Counter POS",
"mid": "886000001130",
"tid": "00000001",
"processor_config_id": "cfg-tsys-001",
"status": "active",
"var_sheet": { "applicationId": "B001" }
}
Schedule Format
Days
Use 3-letter day codes:
| Code | Day |
|---|---|
MON |
Monday |
TUE |
Tuesday |
WED |
Wednesday |
THU |
Thursday |
FRI |
Friday |
SAT |
Saturday |
SUN |
Sunday |
Times
Times are in 24-hour HH:MM format. You can set multiple closes per day:
{
"day": "WED",
"times": ["12:00", "18:00", "23:00"]
}
This closes the batch at noon, 6pm, and 11pm on Wednesdays.
No Close on a Day
Simply omit the day from the schedule. If Saturday and Sunday are not listed, no batch close happens on weekends.
Timezones
DST vs Fixed Timezones: Choose carefully between DST-aware and fixed-offset timezones. Most merchants want DST-aware timezones so the batch close follows "wall clock" time.
DST-Aware Timezones (Recommended)
These follow daylight saving time transitions. 23:00 US/Eastern means 11pm EDT in summer and 11pm EST in winter.
| Timezone | Description |
|---|---|
US/Eastern |
Eastern Time (New York) |
US/Central |
Central Time (Chicago) |
US/Mountain |
Mountain Time (Denver) |
US/Pacific |
Pacific Time (Los Angeles) |
US/Alaska |
Alaska Time |
US/Hawaii |
Hawaii Time (no DST) |
US/Arizona |
Arizona Time (no DST) |
You can also use full IANA zone names like America/New_York, America/Chicago, etc.
Fixed-Offset Timezones
These never change for DST. Use only if you want a fixed UTC offset year-round.
| Timezone | UTC Offset | Notes |
|---|---|---|
EST |
UTC-5 always | Does not switch to EDT in summer |
MST |
UTC-7 always | Does not switch to MDT in summer |
HST |
UTC-10 always | Same as US/Hawaii |
UTC |
UTC+0 always | Universal Coordinated Time |
Example: DST Impact
A batch close at 23:00 US/Eastern:
- Winter (EST): Fires at 04:00 UTC
- Summer (EDT): Fires at 03:00 UTC
A batch close at 23:00 EST:
- Always: Fires at 04:00 UTC (even in summer when "wall clock" Eastern time is EDT)
Managing Schedules
Update an Existing Schedule
PUT /v2/terminals/{terminal_id}
{
"batch_schedule": {
"timezone": "US/Pacific",
"schedule": [
{ "day": "MON", "times": ["22:00"] },
{ "day": "FRI", "times": ["14:00", "22:00"] }
]
}
}
Pause Scheduling (Keep Config)
Send the current timezone and schedule with is_active: false to pause an editable schedule. This object uses create/update defaults, so sending only is_active can replace the timezone and schedule with defaults. Preserve the full configuration when pausing:
PUT /v2/terminals/{terminal_id}
{
"batch_schedule": {
"timezone": "US/Pacific",
"is_active": false,
"schedule": [{ "day": "MON", "times": ["22:00"] }]
}
}
Resume Scheduling
PUT /v2/terminals/{terminal_id}
{
"batch_schedule": {
"timezone": "US/Pacific",
"is_active": true,
"schedule": [
{ "day": "MON", "times": ["23:00"] },
{ "day": "TUE", "times": ["23:00"] }
]
}
}
Important: An active schedule must have at least one day with times configured. Setting is_active: true with an empty schedule will return an error.
Remove Schedule Entirely (Back to Manual)
Set batch_schedule to null:
PUT /v2/terminals/{terminal_id}
{
"batch_schedule": null
}
After removal, the terminal returns to manual batch management.
Updates Without batch_schedule
Updating other terminal fields (name, MID, var_sheet, etc.) does not affect the schedule:
PUT /v2/terminals/{terminal_id}
{
"name": "New Terminal Name"
}
The existing batch schedule is preserved.
Switching Between Auto and Manual
Switching from Auto to Manual
To switch a terminal back to manual batch management, remove the schedule:
PUT /v2/terminals/{terminal_id}
{
"batch_schedule": null
}
Important: When switching to manual, the current open batch stays open. You are now responsible for:
- Closing or releasing batches manually (
POST /v1/batches/{batch_id}/close) - For TSYS and Elavon, opening new batches manually (
POST /v1/batches/open) - For Worldpay, allowing the processor to create the next batch; do not call the open endpoint
- Managing future batch closes or releases after removing the Koard schedule
Switching from Manual to Auto
Enable a schedule on an existing terminal:
PUT /v2/terminals/{terminal_id}
{
"batch_schedule": {
"timezone": "US/Central",
"is_active": true,
"schedule": [
{ "day": "MON", "times": ["22:00"] },
{ "day": "TUE", "times": ["22:00"] },
{ "day": "WED", "times": ["22:00"] },
{ "day": "THU", "times": ["22:00"] },
{ "day": "FRI", "times": ["22:00"] }
]
}
}
If the terminal already has an open batch, the scheduler closes or releases it at the next scheduled time. TSYS and Elavon then open a new batch; Worldpay creates its next batch through the host-capture flow.
Closing a Batch Early
For TSYS, Elavon, and Worldpay, you can close or release an eligible batch early while automated scheduling is enabled. This does not apply to the fixed cycle managed by Fiserv:
POST /v1/batches/{batch_id}/close
TSYS and Elavon require a new open batch after an early close. Call POST /v1/batches/open before the next payment. Worldpay does not support explicit batch opening; its processor creates the next batch when the next transaction is authorized. Do not call the open endpoint for Worldpay.
For TSYS and Elavon, when the scheduler fires later at its scheduled time:
- If it finds an open batch with transactions, it closes and reopens normally
- If it finds an open batch with no transactions (e.g., you just opened it), it cancels the empty batch and opens a fresh one
- If it finds no open batch (e.g., you closed early and didn't reopen), it opens a new one
For TSYS and Elavon, the scheduler can recover a missing open batch on its next run, but payments remain blocked until a batch is open. For Worldpay, continue taking payments through host capture and release the resulting batch at the configured time; no open request is required.
TSYS or Elavon Example: Early Close at 3pm, Scheduled Close at 11pm
- 3:00 PM: You close the batch early via API
- 3:01 PM: You open a new batch via API
- 3:01 PM, 11:00 PM, Transactions accumulate in the new batch
- 11:00 PM: Scheduler fires, closes the batch (with transactions), opens a new one
If you forget to reopen at step 2, the scheduler at 11pm will detect no open batch and open one for you: but any transactions between 3:01 PM and 11:00 PM will have failed because there was no open batch.
TSYS-Specific Behavior
Batch Number Auto-Management
TSYS batch numbers must be between 001-999 and cannot be reused within 5 consecutive days. Koard handles this automatically:
- On open: Queries the last closed batch for the terminal and increments
- On close: Verifies no conflicting batch number, auto-increments if needed
- On duplicate (QD): Automatically retries with the next batch number (up to 10 attempts)
Batch Number Wrapping
When the batch number reaches 999, it wraps around to 001.
Error Handling
| Scenario | Koard's Response |
|---|---|
| Processor unavailable | Retries up to 10 times with backoff |
| Duplicate batch number (TSYS QD) | Auto-increments and retries |
| All retries exhausted | Sends batch.rejected webhook, logs error |
| No open batch to close | Skips close; opens a batch for processors that support explicit open |
Webhook Events
When using automated scheduling, you'll receive the standard batch webhook events:
| Event | When |
|---|---|
batch.submitted |
Batch sent to processor |
batch.accepted |
Processor accepted the batch |
batch.rejected |
Processor rejected the batch, or the scheduler failed after all retries |
batch.opened |
A new batch is explicitly opened, such as for TSYS or Elavon |
Permissions
The following roles can view and manage batch schedules:
| Role | View | Create/Edit | Delete |
|---|---|---|---|
| PSP | ✅ | ✅ | ✅ |
| Partner | ✅ | ✅ | ✅ |
| Merchant | ✅ | ✅ | ✅ |
See also
- Batch and Settlements Overview - Batch concepts
- Running Batches - Manual batch management
- Setting up Webhooks - Webhook configuration

