Package at.hobex.pos.ecr.zvt

ZVTClient

See: Description

Interface Summary

Interface	Description
IntermediateStatusInformationListener	An interface to implement the observer pattern to deliver intermediate status information.

Class Summary

Class	Description
ApplicationLayer
ConfigByte	The Config-Byte is used to set different behavior of the payment terminal.
Helper
IntermediateStatusInformation	The ZVT Interface provides the ability to send intermediate status information to display these for example on a screen.
ReceiptGenerator
ZVTClient	This class provides business methods for transactions over the ZVT Protocol (hobex derivative).
ZVTClientSimulator
ZVTResponse	This class expends the base class Response.java for creating a transaction response object.

Enum Summary

Enum	Description
AgeTags
AgeVerificationAnswer

Package at.hobex.pos.ecr.zvt Description

ZVTClient

This package contains the implementation of the ZVT protocol.

Features

The following business processes are available:

• Logon (Registration)
• Logoff
• Diagnosis
• Status
• Batch totals (Turnover
• Close batch (End of day)
• Repeat receipt
• Purchase (Authorize)
• Cancel (Reversal)
• Pre-Authorize
• Capture (Book Total)
• Pre-Authorize Cancel (Pre-Authorize Reversal)

Requirements

The ECR-API uses log4j as primary log handler. For the integration in your environment it's necessary to add

• hobex-pos-ecr.jar >= 1.3
• log4j.jar >= v.1.2.17 (not when ILogger is used)
• jSerialComm-1.3.11.jar (if serial connection is used)

Configuration

log4j.properties must be included in your classpath, or add loglevel for at.hobex.pos.ecr to your log4j configuration.

If you using the default constructor ZVTClient() hobex.properties must be included in your classpath

Parameters (hobex.properties):

com.host=COMX (IP Address or serial port from the payment terminal)

com.port=20007 (ZVT listen port - default 20007)

com.timeout=180000 (timeout4 according to ZVT specification)

configByte=BE (config byte change the behavior of the payment terminal)

forceRegistration=true (forces an open connection (registration) before an action

timeout3=5000 (timeout4 according to ZVT specification)

Communication

Send the request directly to the terminal.

Simple Usage

try {

  // see overloaded constructors or instantiate with hobex.proerty file
  ZVTClient client = new ZVTClient("COM6");

  // for TCP/IP use
  client = new ZVTClient("192.168.0.10", 20007);

  // to register intermediate status information listener - requires to set the config byte and logon()
  client.addListener(this);

  // set config byte
  ConfigByte.setConfigByte(0xBE);

  // another way to set the config byte
  ConfigByte.setEcrRequiredStatusInformation(true);
  ConfigByte.setEcrControlsAdministrativeFunctions(true);
  ConfigByte.setEcrControlsPaymentFunctions(true);

  // set the terminal behavior
  client.logon();

  // do a simple purchase (reference number is optional)
  ZVTResponse res = (ZVTResponse) client.purchase(1, 1234567);
  log.debug(res.getMerchantReceipt());
  log.debug(res.getCustomerReceipt());

  //if purchase is ok cancel the purchase
  if (res.isOk()) {
    res = (ZVTResponse) client.cancel();

    log.debug(res.getMerchantReceipt());
    log.debug(res.getCustomerReceipt());
  }

  //perform an end of day
  res = client.closeBatch();

  log.debug("Turnover Totals: " + res.getAmount());
  log.debug(res.getAdministraiveReceipt());

  //delete the terminal behavior from former logon()
  client.logoff();
} catch (ECRException e) {
  log.error(e.getMessage());
} catch (ECRCommunicationException e) {
  log.error(e.getMessage());
}

                

Vending mode example

client = new ZVTClient(HOST, PORT, 5000, TIMEOUT_ThreeMinutes, "BE", false);
Response response = client.logon();
Assert.assertTrue(response.isOk());

VendingReadyRequest isReadyAllocation = new VendingReadyRequest();
isReadyAllocation.setCount(5); //set count for possible resends, (each resend takes about 2 seconds)

double amount = 1;
CompletableFuture future = ((ZVTClient) client).purchase(amount, "", isReadyAllocation, AgeTags.EIGHTEEN);

try {
        ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor();

        scheduler.schedule(() -> {
                isReadyAllocation.setReady(true);
                log.debug("Changed goods found.");
        }, 6500, TimeUnit.MILLISECONDS);

        //set goods as available
        res = future.get(6_500, TimeUnit.SECONDS);
        isReadyAllocation.setReady(true);

        //check age
        log.debug("Purchase state: " + res.isOk());
} catch (Exception ex) {
        log.debug("Purchase failed: " + ex.getMessage());
        Assert.fail();
}
        

Receipt (provided from the terminal after setup terminal behavior - see Config-byte & logon))

                 hobex AG
         Josef-Brandst�tterstr. 2
              A-5020 Salzburg
        ---------------------------
        03.04.2018         14:25:42
        0000059    0004      000005
             RECEIPT FOR SALES
        ---------------------------
        Terminal: AH000010
        Receipt#: H004005
        L:************1227
        AID: A0000000041010
        Card: MASTERCARD
        App.: RAIFFEISEN CARD
                  PayPass
        NORMAL PURCHASE
         
        SUM
                 EUR: 1,00
         
        Ref:
         
        Authorization code:00517A2
                 (RC 000)
         Transaction performed
                offline
         
                  NO CVM
         
         AV: 03.39 TI: E DT: 0/0/
             OF: 1/1/ CG: 0/0/

        

ELV Transaction

try {
    // See overloaded constructors or instantiate with hobex.properties file
    ZVTClient client = new ZVTClient("COM6");

    // For TCP/IP use:
    client = new ZVTClient("192.168.0.10", 20007);

    // Do a simple purchase
    ZVTResponse res = (ZVTResponse) client.purchase(1);

    // Check if purchase is an ELV transaction
    if ("ELV".equals(res.getBrand())) {
        // Custom receipt
        String receipt = "";
        receipt += res.getLinesBeforeSignatureOfElvTx();
        receipt += res.getLinesAfterSignatureOfElvTx();
        print(receipt);
    }

    client.logoff();

} catch (ECRException e) {
    log.error(e.getMessage());
} catch (ECRCommunicationException e) {
    log.error(e.getMessage());
}