Getting started

The TIM API Java SDK provides a Java implementation for ECR integration with Worldline terminals. This SDK offers the same feature set as the C SDK with Java-specific idioms and patterns. Complete these configurations before you start the integration.

Maven Dependency

Add the TIM API Java SDK to your project:

<dependency>
    <groupId>com.worldline</groupId>
    <artifactId>timapi-java</artifactId>
    <version>LATEST</version>
</dependency>

Basic Setup

import com.worldline.timapi.*;

public class TerminalExample {
    public static void main(String[] args) {
        // Create terminal settings
        TerminalSettings settings = new TerminalSettings();
        settings.setTerminalId("TERMINAL001");
        settings.setGuides(Guide.RETAIL, Guide.DIALOG);

        // Create terminal instance
        Terminal terminal = new Terminal(settings);

        // Add listener
        terminal.addListener(new TerminalListener() {
            @Override
            public void onTransactionCompleted(TransactionResponse response) {
                System.out.println("Transaction completed: " + response.getResult());
            }
        });

        // Connect and perform transaction
        terminal.connect();
        terminal.login();

        TransactionRequest request = new TransactionRequest();
        request.setAmount(1000); // Amount in cents
        request.setCurrency("EUR");
        request.setTransactionType(TransactionType.PURCHASE);

        terminal.transaction(request);
    }
}

Configuration

Network Settings

TerminalSettings settings = new TerminalSettings();

// Broadcast mode (find terminal by ID)
settings.setTerminalId("TERMINAL001");

// Or direct connect (by IP)
settings.setConnectionType(ConnectionType.DIRECT);
settings.setHostAddress("192.168.1.100");
settings.setHostPort(7784);

Guide Configuration

// Enable multiple guides
settings.setGuides(Guide.RETAIL, Guide.PETROL, Guide.DIALOG);

Synchronous vs Asynchronous

    // Blocks until transaction completes
    TransactionResponse response = terminal.transaction(request);
    if (response.getResult() == Result.SUCCESS) {
        // Transaction successful
    }

    // Returns immediately, result via listener
    terminal.transactionAsync(request);

    // Handle result in listener
    terminal.addListener(new TerminalListener() {
        @Override
        public void onTransactionCompleted(TransactionResponse response) {
            // Process response
        }
    });

The TIM API uses two different types of automatisms:

Automatisms

Pre-automatisms

Actions performed automatically before a function can be called. For example, a transaction can be called in disconnected state without having called connect, login, and activate in advance. These are called automatically by the TIM API.

Post-automatisms

Actions triggered after an operation has been performed. Controlled by:

Setting	Description
auto_commit	Automatically performs a commit after a transaction
fetch_brands	Automatically calls application_information after connect

Both are enabled by default.