Use the Java ECR SDK to integrate payment acceptance into Java-based POS applications and billing systems.

This guide provides instructions for:

• Configuration management
• Connectivity testing
• Transaction execution
• Response handling

For environment setup and SDK details, refer to the Java SDK Integration Library.

Integration Approaches

The Java ECR SDK supports the following integration approaches.

Use the DLL-free approach for new projects.

Use the DLL-based approach only when maintaining existing integrations.

Supported Connections

SDK Transaction Flow

Set Configuration → Get Configuration → Test Connectivity → Execute Transaction → Receive Response → Parse Response

Business Transaction Flow

Connect → Register Terminal (17) → Start Session (18) → Purchase (0) → Disconnect

Integration Steps

Step 1: Configure POS Library

Configure terminal communication parameters before performing connectivity tests or transactions.

Use setConfiguration() to save terminal communication settings.

// Signaturevoid setConfiguration(ConfigData configData)

ConfigData configData = new ConfigData();configData.setTcpIP("192.168.0.100");configData.setTcpPort("8080");configData.setComPortNumber("COM3");configData.setRetryCount(2);configData.setConnectionTimeOut(30);configData.setPriority1(1);configData.setPriority2(2);configData.setConnectivityFallBackAllowed(true);PosLibManager.getInstance().setConfiguration(configData);

Step 2: Get Configuration

Retrieve the current SDK configuration.

Use getConfiguration() to load saved communication settings.

// Signatureint getConfiguration(ConfigData configData)

ConfigData configData = new ConfigData();int result =    PosLibManager.getInstance()        .getConfiguration(configData);

Step 3: Test Connectivity

Verify communication with the payment terminal before processing transactions.

TCP/IP Test

Use testTcp() to verify network connectivity.

// Signatureboolean testTcp(String ip, String port)

boolean connected =    PosLibManager.getInstance()        .testTcp("192.168.0.100", "8080");

Serial COM Test

Use testSerialCom() to verify serial communication.

// Signatureboolean testSerialCom(String portName)

boolean connected =    PosLibManager.getInstance()        .testSerialCom("COM3");

Step 4: Register Terminal

Register the terminal before starting a transaction session.

Step 5: Start Session

Start a transaction session before performing financial transactions.

Transaction Processing

Step 6: Execute Transaction

Create a transaction request and submit it to the terminal.

The SDK prepares the transaction payload and sends it to the terminal using doTransaction().

Prepare Request Data

String request =    handleRequestData(        txnType,        dateTime,        ecrReferenceNo,        printMode    );

Execute Transaction

PosLibManager.getInstance().doTransaction(    StringUtil.asciiToHex(request),    signature,    txnType,    listener);

Supported Transaction Types

Step 7: Response Handling

Transaction responses are returned asynchronously through the TransactionListener.

Implement the listener to process successful responses, intermediate actions, and failures.

TransactionListener listener =
    new TransactionListener() {

        @Override
        public void onSuccess(
                String paymentResponse) {

            String terminalResponse =
                StringUtil.hexToASCII(
                    paymentResponse);

            handleResponseFields(
                terminalResponse);
        }

        @Override
        public void onNext(String action) {

            // Handle intermediate actions

        }

        @Override
        public void onFailure(
                String errorMsg,
                int errorCode) {

            System.out.println(
                errorCode + " : " + errorMsg);
        }
    };

Response Processing

The SDK converts the terminal response from HEX to ASCII and parses the response fields.

String terminalResponse =    StringUtil.hexToASCII(paymentResponse);handleResponseFields(terminalResponse);

Use handleResponseFields() to process terminal response data.

public void handleResponseFields(String input)

The available response fields depend on the transaction type and terminal response.

Response Flow

Receive Response → Convert HEX to ASCII → Parse Fields → Process Result

Request Processing

The SDK creates transaction requests using handleRequestData().

private String handleRequestData(    String txnType,    String dateTime,    String ecrReferenceNo,    String printMode)

The request payload can include:

• Transaction type
• Transaction date and time
• ECR reference number
• Amount
• Cashback amount
• Print mode
• Original transaction details

The generated request is converted to HEX format before transmission to the terminal.

String request =    handleRequestData(        txnType,        dateTime,        ecrReferenceNo,        String.valueOf(printMode)    );

Transaction Listener Lifecycle

Key Rules

• Configure communication settings before testing connectivity.
• Verify connectivity before executing transactions.
• Register the terminal before starting a session.
• Start a session before performing financial transactions.
• Use TCP/IP as the primary communication method whenever available.
• Process terminal responses through the transaction listener callbacks.
• Use Serial COM as a fallback communication method when required.

Final Integration Flow

Set Configuration → Get Configuration → Test Connectivity → Register Terminal (17) → Start Session (18) → Execute Transaction → Receive Response → Parse Response → Disconnect

Installation Notes

• Requires a supported Java Runtime Environment (JRE) or Java Development Kit (JDK).
• Requires access to a supported payment terminal.
• Supports TCP/IP and Serial COM communication.
• Configure terminal and cashier information before processing transactions.
• Verify connectivity before executing transactions.
• Use the DLL-free integration approach for all new implementations.