Card batches

The card batch object

A card batch object is created as a the result of a card payment processed through any Helcim payment tool, including the Payment API or HelcimPay.js. A card batch may have one or more transaction objects stored within it and once closed will go through a settlement process and ultimately be deposited into the provided bank account.

A card batch stores a number of core details about your payments, including:

• The unique cardBatchId value that is also stored in any transaction object included in the card batch.
• The date values for when the card batch was created, last updated, and closed.
• The card batchNumber and whether the card batch is in an open or closed state.
• The card terminalId that the transactions in this card batch were processed on.

// Example card batch object

{
  "id": 4209764,
  "dateCreated": "2024-12-05 03:04:18",
  "dateUpdated": "2024-12-05 04:35:30",
  "dateClosed": "0000-00-00 00:00:00",
  "closed": false,
  "terminalId": 54181,
  "batchNumber": 559,
  "netSales": 819,
  "totalSales": "819.0000",
  "totalRefunds": "0.0000",
  "totalReversed": "0.0000",
  "totalRefundsReversed": "0",
  "countTotal": 7,
  "countApproved": "7",
  "countDeclined": "0"
}

Card batch closures

All payments processed through Helcim payment tools create or are added to an existing open card batch object. Understanding default card batch functionality is important for knowing how payments move through settlement and ultimately get deposited to the merchant on live Helcim accounts.

Some key functionality worth noting includes:

• When no card batch is open, the first successful payment will open a new card batch.
• A card batch will close automatically at 5PM in your local time, unless auto-settlement has been disabled for your card terminal.
• If auto-settlement has been disabled for your card terminal, card batches must be manually settled, or will close after 24 hours of being open.
• A card batch with a closed value of "true", indicates that the transactions in that batch will go through or have gone through a settlement process with the customers issuing banks.

Settle an open card batch

A card batch will close automatically by default, however if you have disabled the automatic closure functionality for card batches on a specific card terminal, then you can either:

• Manually settle the card batch through the Helcim account Payments section
• Manually settle the card batch through the Settles an open card batch endpoint

Settling a card batch will begin the settlement process and any payments in the batch will be subject to transaction fees and can no longer be voided.

Card batch statistics

To get more detailed payment statistics for your card batch, you can use the query parameter for collect-stats in both the Get card batch and Get card batches endpoints.

Card batch statistics includes a range of additional batch attributes, including:

• Net sales and total sales amounts
• Total refunds and reverse amounts
• Counts of total payments, approved payments, and declined payments

Card batch endpoints

Retrieve and settle existing card batch objects using the following endpoints.

• Get card batches
• Get card batch
• Settle an open card batch