Overview

This class library is used for communication between any retail pos software or others and Hobex POS devices. Base for all integration scenarios is ECRBase. ECRBase provides you with all the necessary business methods to integrate payment business scenarios in your software.

With just a few lines of code, you are able to trigger a purchase transaction for a Hobex Terminal.

Don't hesitate to contact us directly under ecr@hobex.at

Download the latest version of the hobex Java API

hobex Java API 1.7.01

2026-04-24 Release notes:

hobex Java API 1.6.21

2026-03-09 Release notes:

hobex Java API 1.6.20

2026-02-09 Release notes:

hobex Java API 1.6.19

2026-02-02 Release notes:

hobex Java API 1.6.18

2025-10-02 Release notes:

hobex Java API 1.6.17

2025-06-25 Release notes:
- ZVTClient: Add cashback integration.
- TecsClient: Add check of correct Tid to start with 03 or only with 3 at the start.
- TecsClient: Update checkTid made public.
- ZVTClient: Add purchase method to take a parameter that represents the required age for this tx, either as int or as a enum (AgeTags).

hobex Java API 1.6.16

2024-11-29 Release notes:
- ECRBase: Bugfix newTransactionId() returns now the correct format (20 digits)
- TecsClient: Bugfix Capture was not working correct (sends a cancel instead of capture)
- TecsClient: Bugfix End of day/CloseBatch response was not parsed correct - fixed

hobex Java API 1.6.15

2024-09-18 Release notes:
- ZVTClient: Add Brainbehind support (loyalty cards)
- TECSClient: Add digital signature (Response delivers path to image if signature was captured digital)
- TECSClient: getTransactionDetails - Bugfix (for internal TC)

hobex Java API 1.6.13

2024-08-12 Release notes:
- TecsClient - new method getTransactionDetails. Get the response from a former transaction. So it is possible to check in case of unclear transaction state.

hobex Java API 1.6.11

2023-12-03 Release notes:
- ZVTClient: Add Brainbehind support (loyalty cards)
- TECSClient: Add digital signature (Response delivers path to image if signature was captured digital)
- TECSClient.getTransactionDetails - Bugfix (for internal TC)

hobex Java API 1.6.10

2023-09-26 Release notes:
- ZVTClient: Add sending TIP to terminal (terminal software has to support this, may an update is necessary)
- ZVTClient: If TIP override is enabled it is possible that the customer add tip to the payment -> see Response.Amount contains the total amount (initial amount + tip amount), the TIP is available in Response.TipAmount
- ZVTClientSimulator - add TIP capabilities
- TECSClientSimulator - add TIP capabilities

hobex Java API 1.6.9

2023-09-26 Release notes:
- HOTFIX: ZVT always accidentally sends a Euro TIP. With the new terminal software for the ZVT terminals, this error has the effect that it is booked!

hobex Java API 1.6.8

2023-02-13 Release notes:
- TecsClient Bugfix: if several messages are contained within one response - fix that the parsing works
- TecsClient: Stream will be closed now before the Socket is closed (obviously best practice)

hobex Java API 1.6.8

2023-05-23 Release notes:
- TerminalSimulator TecsClient - Bugfix: returns everytime the same response

hobex Java API 1.6.7

2023-01-12 Release notes:
- TecsClient close batch: Get detailed information about the turn-over (for every card brand).
- TecsClient referenced refund: Bugfix, sets correct origin identifier
- SmartPOSClient: read MIFARE card -> returns UUID in UpperCase
- ZVTClient: Add new constructor and hobex.properties parameter (delayBetweenCommands) to force a delay between two commands.
- ZVTClient: Add baudRate and stopBits to hobex.properties file.
- ZVTClient: Logon, Logoff and Diagnosis now sets the Response.isOk(), ResponseText and ResponseCode correct

hobex Java API 1.6.6

2022-11-02 Release notes:
- CTLSCardListener: fix wrong method signature
- TecsClient: reconciliation ends up in loop - fixed
- ZVTClient: serial connection, baud rate was not set to given value
- TecsClient: add Abort command
- Update SmartPOS-SDK.jar to V2.10.0
- TecsClient add batchTotals: Command to force the terminal to send an overview about the stored turnover sum (ZVTResponse#getAmount() holds the turnover sum).

hobex Java API 1.6.5

2022-09-20 Release notes:
- TecsClient add referenced refund
- Add new TIP function to the hobex VIA terminals (not Pinpad-Mode!). Now it is possible to activate a TIP screen on the device and the ecr interface returns the new total amount with tip if the customer enters tip. The cashregister has to implement a **check if TIP was given** before we can activate this feature!
- TecsClient add reconciliation - returns detailed overview about the turnover

hobex Java API 1.6.4

2021-11-18 Release notes:
- Unattended Terminal Bugfix: sometimes the SDK stucks while parsing response, fixed
2021-11-04 Release notes:
- SmartPOSClient: new Class extends the TecsClient, supports extended functionality for SmartPOS Devices like hobex VIA. Enables the NFC card read for supported cards. For further information see CTLSCardListener. Minimal requirement on hobex VIA - PaymentService >= V1.73, SW-Pkg: 10.18.0
- Removed deprecated CA
- Response.getShortCustomerReceipt - returns a short customer receipt, it is mandatory to add this receipt physical to the bill
- Response - Italian is now available as receipt language -> "IT"

hobex Java API 1.5.3

2021-05-26 Release notes:
- TecsClient Bugfix: TID 00000000 is now allowed to set (mandatory for hobex VIA)

hobex Java API 1.5.2

2021-05-25 Release notes:
- This version is not compatible with previous if you are using the reference number -> please switch from long to string!
- Reference is now alphanumeric. A maximum of 20 characters with the following special characters are allowed for the reference! -_+*#.()/%&!\"$%&\/=?:,;{[]}~<>|
- Removed deprecated methods
- TecsClient: new constructor to be able to transfer the merchant header in it. This is required when generating the payment receipt.
- Response: setter & getter to set the merchant header instead of the constructor (only for TecsClient mandatory)
- TecsClient: Checks now if the TID and Password is given in the correct format

hobex Java API 1.4.11

2021-02-10 Release notes:
- TecsClient Bugfix: If the network connection breaks during a request, it ends up sometimes in an infinity loop
- Add seasons greetings (christmas, easter) to the ZVT-Simulator (batch totals, close batch)

hobex Java API 1.4.10

2020-11-27 Release notes:
- Remove set Locales during receipt generation
- Add TIP: Purchase accepts now TIP
- TecsClient: add CloseBatch (End of day) command
- TecsClient: add CheckConnection command
- Terminal Simulator->ZVTClient: add short customer receipt
- Bugfix: Add missing linebreak at Receipt
- Send release notification by mail

hobex Java API 1.4.8

2020-07-22 Release notes:
- TecsClient Bugfix: Sometimes the Response-Message is not correct, catches this case if there is a problem during message parsing
- TecsClient: add Diagnosis command
- TecsClient: add Restart payment application command
- Response: Add signature field to unattended receipt
- Terminal Simulator->TecsClient: Add Diagnosis, CloseBatch (coming soon in production)

hobex Java API 1.4.6

2020-07-22 Release notes:
- Add minimal receipt information to documentation
- TecsClient-ViA: Open System Menu command
- TecsClient: MOTO new messagetype
- ZVTClient: Logon, Logoff command (set openCommunication, closeCommunication to deprecated)

hobex Java API 1.4.4

2020-04-23 Release notes:
- Added Terminal Simulator (TECSClient, ZVTClient) to JavaAPI-Test GUI (Extra -> Terminalsimulator). This Simulator simulates a Terminal on localhost for dev-purposes. So it is possible to test implementation without a physical terminal.
- Added milliseconds to the generated TxId (Pattern: '0000yyyyMMddHHmmssSS' - 20 digits)
- TecsClient: Correct the calculation of the Length-Field
- TecsClient: Removed the tailing delimiter '\0'
- TecsClient: Due to the card scheme regulations set gratuity to deprecated
- Response - GenerateReceipt: Add CVM and 'Contactless' to receipt
- Android: API Version is now displayed in Logfiles and on the Receipt, Receipt date & time now displayed in the correct pattern
- New overloaded Methods for cancel, capture, preauthCancel: it is possible to send also an own txID to this requests

hobex Java API 1.4.1

2019-10-23 Release notes:
- Logging: It is now possible to use own Logger-Implementation/Frameworks. Please read the at.hobex.pos.logger Package spec.

hobex Java API 1.3.30

Release notes:
- Bugfix - ZVTClient: For some amounts, one cent is not sent to the terminal.

hobex Java API 1.3.29

Release notes:
- Add download section to doc
- ZVTClient: supports negative completion command

hobex Java API 1.3.22

Release notes:
- ZVTClient: auto detect the receipt code page (Supported CP: CP437, ISO8859_1)
- Parameterless cancel is set to deprecated

Download the hobex JavaAPI-Test GUI (including Terminal simulator) here

This GUI implements the hobex Java API to demonstrate the functionality

It is also possible to simulate a virtual terminal on localhost. This Simulator simulates the responses from a real Terminal for dev-purposes. So it is possible to test implementation without a physical terminal.

Interface matrix / Overview about the supported interfaces

Receipt requirements

The minimal requirement to the receipt are:

Receipt header (merchant name)
Transaction Date - Response.getTransactionDate()
Transaction Time - Response.getTransactionDate()
Transaction amount - Response.getAmount()
Currency - Response.getCurrency()
Terminal ID - Response.getTerminalID()
Receipt Number - Response.getReceiptNo()
Transaction type - Response.getTransactionType()
Brand - Response.getBrand()
PAN (Card number masked) - Response.getPAN()
Response Code - Response.getResponseCode()
Signature field depending on CVM - Response.isSignature() == true -> print signature line
Client ID (if multi merchant) - Response.getClientId()

The receipt for customers must at least be offered for printing. Merchant receipt is sufficient digitally (however, it must be possible to reprint) - Attention for signature-based transactions -> signature is also sufficient digitally, but must be combined with the receipt when printing.

In the case of subsequent filing, a PDF document (or other related document) must be able to be delivered with the data (from the dealer). A text file with the information is not enough.

Example for using the inheritance with the hobex Java API

public void test() {
  // To dynamically use the different protocols can be deriving from the ECRBase
  // class.
  // This is the example of our TestGUI which is available to test the different
  // API functions.
  // The different parameter - set up by your program configuration
  // Please note that the protocols requires different parameters
  String tid = "3512186";
  String password = "";
  String host = "tca.hobex.at";
  int port = 9991;
  int timeout3 = 5000;
  int timeout4 = 180000;
  String configByte = "BE";
  int baud = 9600;
  int stopbits = 2;
  String language = "EN";
  boolean ssl = true;
  //To set the trustStore -> TECSClient SSL
  System.setProperty("javax.net.ssl.trustStore", "hpg-ecr-2018.ts");
  System.setProperty("javax.net.ssl.trustStorePassword", "XXXXXXXX");
  // Switch over the different protocols.
  // In this example the selected Protocol simulate a drop down or something else
  // from your config screen.
  // 0 - TecsClient
  // 1 - ZVTClient
  // 2 - FirstDataOCP (Open Com Protocol) - DEPRECATED!
  // the selectedConnectionType indicates the different connection types and also
  // the possibility to read the settings from the app.config
  // Code Snippet:
  int selectedProtocol = 0;
  int selectedConnectionType = 1;
  ECRBase terminal = null;
  switch (selectedProtocol) {
  case 0:
    switch (selectedConnectionType) {
    case 0:
      terminal = new TecsClient();
      break;
    case 1:
      terminal = new TecsClient(tid, password, host, port, timeout4, ssl, language);
      break;
    }
    break;
  case 1:
    switch (selectedConnectionType) {
    case 0:
      terminal = new ZVTClient();
      break;
    case 1:
      terminal = new ZVTClient(host, port, timeout3, timeout4, configByte);
      terminal.setLanguage(language);
      break;
    case 2:
      terminal = new ZVTClient(host, baud, stopbits, timeout3, timeout4, configByte);
      terminal.setLanguage(language);
      break;
    }
    break;
  case 2:
    switch (selectedConnectionType) {
    case 0:
      terminal = new FirstDataOCP();
      break;
    }
    break;
  }
  // to a simple purchase with cancel
  Response response = null;
  try {
    terminal.logon();
  } catch (Exception e) {
  }
  double amount = 1;
  // save the transaction id for the "TECSClient Limitation"
  String transactionID = terminal.newTransactionId();
  try {
    response = terminal.purchase(transactionID, amount);
    System.out.println(response.getMerchantReceipt());
    if (response.isOk()) {
      // Plese keep in mind that for a cancel ZVTClient needs the receipt number and
      // TECSClient use the transaction id
      if (terminal instanceof ZVTClient) {
        response = terminal.cancel(response.getAmount(), response.getReceiptNo());
      } else {
        response = terminal.cancel(response.getAmount(), response.getTransactionId());
      }
      System.out.println(response.getMerchantReceipt());
    }
  } catch (Exception e) {
    // TECS Client limitation
    int maxAttempts = 10;
    for (int i = 0; !(response != null && response.isOk()) && i < maxAttempts; i++) {
      try {
        // wait for internet connection
        Thread.sleep(5000);
        // check if terminal is online
        response = terminal.status();
        if (response.isOk()) {
          response = terminal.cancel(amount, transactionID);
        }
      } catch (Exception ex) {
      }
    }
  }
  try {
    terminal.logoff();
  } catch (Exception e) {
  }
}

Packages

Package

Description

at.hobex.helper

at.hobex.pos.ecr

There are different protocols implemented in the API.

at.hobex.pos.ecr.smartpos

SmartPOSClient

at.hobex.pos.ecr.tecs

TecsClient

at.hobex.pos.ecr.zvt

ZVTClient