Running Batches

Learn how to create, manage, and process batches with Koard's payment platform.

Get started with Koard

Koard provides comprehensive batch processing capabilities for managing transactions and settlements. Whether you choose to let Koard handle batches automatically or manage them yourself, this guide covers all the essential operations and best practices.

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.

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:

• Automatic Management: Koard handles all batch operations automatically
• Status Tracking: Automatic transaction status tracking and reconciliation
• Error Handling: Built-in retry logic and error recovery
• 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: Implement retry logic for failed operations

Core Batch Operations

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

Listing Batches

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

Query Parameters:

• account_id (optional): Filter by owning account
• terminal_id (optional): Filter by terminal ID
• status_filter (optional): Filter by batch status (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: The batch ID for the processor (must be unique per MID/TID combination)

Closing a Batch

POST /v1/batches/{batch_id}/close

No request body is required. The batch must be in an open status to be closed.

Editing an Open Batch

PUT /v1/batches/{batch_id}/edit
{
  "added_transactions": ["txn_123", "txn_456"],
  "removed_transactions": ["txn_789"]
}

Required Fields:

• 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

Webhook Integration

Every transaction processed through Koard triggers a webhook event. Upon delivery, you'll receive:

• Transaction Data: All required fields for batch processing
• TLV Tags: General TLV tags from the payment device
• Status Information: Real-time transaction status updates
• Batch Context: Information about which batch the transaction belongs to

{
  "event": "transaction.processed",
  "data": {
    "transactionId": "txn_abc123def456",
    "approvalCode": "123456",
    "responseCode": "00",
    "amount": {
      "auth": 1000,
      "settled": 1000,
      "tip": 0
    },
    "timestamp": "2024-01-15T14:30:00Z",
    "batchId": "batch_xyz789",
    "tlvTags": {
      "aci": "Y",
      "void": "N"
    }
  }
}

Batch Lifecycle Management

Batch Statuses

A batch progresses through several statuses during its lifecycle:

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. Close at Any Time: Batches can be closed at any point (typically end of business)
2. Constraint: You can only close an open batch
3. Rejected Batches: If a batch is rejected or partially approved:
   • Add all rejected transactions to a new open batch
   • Close the new batch again
   • Maintain batch number sequential order

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:

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

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

Error Handling and Recovery

Failed/Rejected Batches

When batches fail or are rejected:

1. Status Information: Koard returns detailed status information
2. Failure Details: Specific information about what failed
3. Retry Logic: Automatic retry mechanisms for recoverable errors
4. Manual Approval: Rejected batches can be manually approved via the portal on TSYS

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

• Retry Logic: Implement retry logic for failed batch operations
• 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