Java Library

Java Library

The Java EPAS Client Library provides the same ECR-to-terminal integration model as the .NET library, with Java package names and Java callback signatures. The main class is se.westpay.epas.connections.classes.EpasClient.

Requirements

Item	Value
Artifact	library-1.4.5.jar
Main package	se.westpay.epas
Main client	EpasClient
Required callback interface	IClientApp
Common return wrapper	Pair<ApiDefinitions.ApiResult, T>

Important Packages

Package	Purpose
se.westpay.epas.connections.classes	EpasClient, ReceiptData, and connection-level classes.
se.westpay.epas.services	IClientApp, ApiDefinitions, terminal environment, operating parameters, enums.
se.westpay.epas.requests	Request models such as PurchaseRequest and RefundRequest.
se.westpay.epas.responses	LoginResponse, TransactionResponse, EnableReadersResponse, and other response models.
se.westpay.epas.utils.export	Utility types such as Pair and IPEndPoint.

Minimal Setup

java
import se.westpay.epas.connections.classes.EpasClient;
import se.westpay.epas.connections.classes.ReceiptData;
import se.westpay.epas.responses.TransactionResponse;
import se.westpay.epas.services.ApiDefinitions;
import se.westpay.epas.services.IClientApp;
import se.westpay.epas.utils.export.Pair;

public final class EcrApplication implements IClientApp {
    private final EpasClient epas;

    public EcrApplication() {
        epas = new EpasClient(this);
        epas.complete();
    }

    @Override
    public void Display(String text) {
        System.out.println(text);
    }

    @Override
    public void PrintReceipt(ReceiptData receipt) {
        System.out.println(receipt.generateSimpleReceipt(32));
    }

    @Override
    public Pair<Boolean, Boolean> VerifySignature(String displayText) {
        Display(displayText);
        return new Pair<>(true, true);
    }

    @Override
    public void Log(ApiDefinitions.LogLevel level, String text) {
        System.out.printf("[%s] %s%n", level, text);
    }

    // Implement the remaining IClientApp callbacks for production use.
}

Callback Interface

The Java IClientApp interface includes required operational callbacks and notification callbacks.

Method	Purpose
Display(String text)	Shows cashier-facing terminal text.
PrintReceipt(ReceiptData receipt)	Handles cardholder and merchant receipts.
PrintReport(String report)	Handles textual reports from the terminal.
VerifySignature(String displayText)	Returns whether the cashier accepted the cardholder signature.
HandleVoiceReferral(String displayText)	Collects an approval code when voice referral is needed.
PaymentCodeRequired(String displayText)	Collects a payment code for cards that require one.
VatAmountRequired(String displayText)	Collects VAT or sales tax amount if required.
LoyaltyCardPresented(String cardNumber)	Handles a loyalty card presented to the terminal.
CheckDccOnOriginalTransaction(String displayText)	Indicates whether DCC was used for the original purchase during a DCC refund.
ParameterDownloadAvailable(String displayText)	Allows or delays a terminal parameter download.
Log(ApiDefinitions.LogLevel level, String text)	Receives library logs.
LinkStatusNotification(boolean state)	Receives terminal link status changes.
BusyStatusNotification(boolean state)	Receives terminal busy status changes.
CardActionNotification(boolean cardInserted)	Receives card inserted or removed notifications.
CardAcceptedNotification(ApiDefinitions.CardAcceptedEventArgs args)	Receives masked card details after terminal acceptance.

Methods that return Pair<Boolean, T> use the first value to indicate whether the transaction should continue and the second value to carry the answer.

Configure the Client

Some Java settings are supplied through setParameter(...).complete(). Call complete() after setting parameters and before connecting.

java
epas.setParameter(ApiDefinitions.AppParamIds.DUE_TIME_FOR_TERMINAL_KEEPALIVE_TIMER, 1000L)
    .setParameter(ApiDefinitions.AppParamIds.TIMER_INTERVAL_FOR_TERMINAL_KEEPALIVE_TIMER, 10000L)
    .setParameter(ApiDefinitions.AppParamIds.MAX_ACCEPTABLE_MESSAGE_LENGTH, 80000)
    .complete();

Connect and Login

java
import se.westpay.epas.responses.LoginResponse;
import se.westpay.epas.utils.export.IPEndPoint;

ApiDefinitions definitions = new ApiDefinitions();

ApiDefinitions.TerminalNetworkConnection connection =
    definitions.new TerminalNetworkConnection();
connection.TerminalConnectionDetails = new IPEndPoint("192.168.10.25", 6001);
connection.UseKeepAlive = true;

ApiDefinitions.ApiResult connectResult = epas.connectNetwork(connection, false);
if (connectResult != ApiDefinitions.ApiResult.OK) {
    throw new IllegalStateException("Connect failed: " + connectResult);
}

ApiDefinitions.TerminalEnvironment environment =
    definitions.new TerminalEnvironment();
environment.TerminalId = "80000082";
environment.StoreId = "store_1";
environment.WorkstationId = "pos_1";
environment.OperatorId = "cashier_1";
environment.SetLanguageCode("sv-SE");
environment.ConfigurationServer = new IPEndPoint("185.27.171.42", 55133);
environment.AuthorisationServer = new IPEndPoint("185.27.171.42", 55144);

Pair<ApiDefinitions.ApiResult, LoginResponse> loginResult = epas.login(environment);
if (loginResult.getKey() != ApiDefinitions.ApiResult.OK
    || !loginResult.getValue().isLoggedIn()) {
    throw new IllegalStateException("Login failed: " + loginResult.getKey());
}

Supported Operational Surface

The Java wrapper mirrors the standard EPAS workflows used in .NET:

• connect, disconnect, login, logout
• purchase, refund, reversal, cash advance
• pre-amount purchase and send amounts
• abort
• last transaction
• enable or disable card readers
• administrative operations
• receipt, report, display, and cashier callbacks

Use the shared pages for cross-language flow examples and behavioural notes.

Transactions

Java transaction methods return a Pair containing the API result and the typed response. ApiResult.OK means the request or response exchange succeeded; use the response object to check approval.

Purchase

java
ApiDefinitions.PurchaseTransactionAmounts amounts =
    definitions.new PurchaseTransactionAmounts(100.00);

Pair<ApiDefinitions.ApiResult, TransactionResponse> result = epas.purchase(amounts);

if (result.getKey() == ApiDefinitions.ApiResult.OK) {
    TransactionResponse response = result.getValue();
    if (response.isApproved()) {
        completeSale(response.getTransactionReference(), response.getFinalAmount());
    } else {
        showDecline(response.toString());
    }
}

Purchase with Cashback

java
ApiDefinitions.PurchaseTransactionAmounts amounts =
    definitions.new PurchaseTransactionAmounts(100.00, 20.00);

Pair<ApiDefinitions.ApiResult, TransactionResponse> result = epas.purchase(amounts);

Alternative Payment Method Purchase

java
Pair<ApiDefinitions.ApiResult, TransactionResponse> result =
    epas.purchase(100.00, "Swish");

If a requested alternative payment method is unavailable on the terminal, the transaction is aborted.

Pre-Amount Purchase

java
CompletableFuture.runAsync(() -> {
    Pair<ApiDefinitions.ApiResult, TransactionResponse> result =
        epas.purchaseBeforeAmount();
    handleTransactionResult(result.getKey(), result.getValue());
});

ApiDefinitions.PurchaseTransactionAmounts amounts =
    definitions.new PurchaseTransactionAmounts(100.00, 0.00);

ApiDefinitions.ApiResult sendResult = epas.sendPurchaseAmounts(amounts);

Refund

java
Pair<ApiDefinitions.ApiResult, TransactionResponse> result = epas.refund(45.00);

Reversal

java
Pair<ApiDefinitions.ApiResult, TransactionResponse> result =
    epas.reversal(transactionReference);

Abort

java
ApiDefinitions.ApiResult result = epas.requestTransactionAbort();

The abort request may arrive too late to stop the transaction. Always process the final transaction response and receipts.

Receipt Handling

java
@Override
public void PrintReceipt(ReceiptData receipt) {
    receiptRepository.save(receipt);
    String printable = receipt.generateSimpleReceipt(32);
    receiptPrinter.print(printable);
}

Use the individual ReceiptData fields when your ECR needs a custom receipt layout, electronic receipts, or reporting data.

Related Pages

• EPAS Client Library overview
• .NET Library
• Java Function Reference
• Swift Library
• Transactions
• Receipts and Events