The Java ECR SDK enables Java-based POS and ERP applications to integrate payment functionality with supported payment terminals.

The SDK provides APIs for:

Terminal configuration
Connectivity testing
Transaction execution
Request generation
Response processing

For transaction integration procedures, see Java ECR SDK Integration.

Prerequisites

Install the required environment before using the SDK.

Java Development Kit (JDK) 8 or later
Supported Windows operating system
Network or Serial COM access to the payment terminal
Java ECR SDK library package

Note: Earlier versions of the SDK required a native DLL dependency through java.library.path. The current SDK supports DLL-free Java integration.

Supported Integration Modes

Approach	Recommended	Description
DLL-Free Integration	✔	Recommended for new integrations
DLL-Based Integration	Supported	Available for legacy deployments

Use the DLL-free approach for all new implementations.

Use the DLL-based approach only for backward compatibility.

Library Import

Import the required SDK classes into your application.

import com.nami.poslib.PosLibManager;
import com.nami.poslib.models.ConfigData;
import com.nami.poslib.listener.TransactionListener;

Core Components

The SDK provides the following core components.

Component	Description
PosLibManager	Main SDK manager used for configuration, connectivity testing, and transaction execution
ConfigData	Stores communication and terminal configuration
TransactionListener	Handles transaction responses and status callbacks
handleRequestData()	Generates transaction request payloads
handleResponseFields()	Parses and processes terminal responses

Configuration APIs

Set Configuration

Use setConfiguration() to save terminal communication settings.

void setConfiguration(ConfigData configData)

Get Configuration

Use getConfiguration() to retrieve saved configuration values.

int getConfiguration(ConfigData configData)

Connectivity APIs

TCP/IP Connectivity Test

Use testTcp() to verify TCP/IP communication.

boolean testTcp(String ip, String port)

Serial COM Connectivity Test

Use testSerialCom() to verify serial communication.

boolean testSerialCom(String portName)

Transaction API

Use doTransaction() to send requests to the payment terminal.

void doTransaction(
    String request,
    String signature,
    int txnType,
    TransactionListener listener)

Transaction Example

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

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

Transaction Listener

Implement TransactionListener to process transaction events.

TransactionListener listener =
    new TransactionListener() {

        @Override
        public void onSuccess(
                String paymentResponse) {

            String terminalResponse =
                StringUtil.hexToASCII(
                    paymentResponse);

            handleResponseFields(
                terminalResponse);
        }

        @Override
        public void onNext(String action) {

            // Intermediate processing

        }

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

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

Configuration Model

The SDK uses the ConfigData model to store communication settings.

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);

Communication Priority

Priority	Description
1	TCP/IP
2	Serial COM

TCP/IP should be configured as the primary communication channel whenever available.

Error Handling

Handle the following conditions in your application.

Condition	Recommended Action
Connectivity failure	Verify IP address, port number, or COM port configuration
Connection timeout	Retry the operation or notify the user
Invalid request data	Validate request parameters before submission
Transaction failure	Process the error returned through `onFailure()`
Response parsing failure	Verify the terminal response format

Security Considerations

Protect transaction reference numbers from unauthorized modification.
Validate request data before submitting transactions.
Restrict access to terminal communication settings.
Store sensitive configuration values securely.

Runtime Behavior

The SDK manages terminal communication and transaction processing.

The runtime sequence is:

Set Configuration → Test Connectivity → Register Terminal → Start Session → Execute Transaction → Receive Response → Parse Response → Disconnect

Transaction Flow

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

Installation Notes

Install JDK 8 or later.
Configure TCP/IP or Serial COM communication settings.
Verify terminal connectivity before executing transactions.
Use DLL-free integration for all new implementations.