The TIM API is the standard application interface for ECR integration using SIX Payment Services terminals.

TIM API provides a comprehensive feature set to support the requirements of several different markets. This guideline is intended to be used by ECR integrators that need to implement the TIM API functionality in their products.

The following document contains an overview structure, description of the TIM API modes synchronous/asynchronous and describes the corresponding functions, notifiers and data elements that can be used with the TIM API. Furthermore implementation examples are provided. Nevertheless always the corresponding description of a function or data element is authoritative, not the examples.

Before starting with the detailed implementation guide, make sure that you read the Simple Implementation Guide first.

The TIM API is available for multiple platforms. Due to such diversity the support for the TIM API is limited to certain standards. Those are the minimal system requirements:

• Java 7 JRE
• Android: API Level 16 (Android 4.1, Jelly Bean)
• Android: API Level 26 for Log Rotation Handling

The configuration of the Terminal can be done in two ways:

1. In a configuration file “TimApi.cfg”.
2. Using / configuring the TerminalSettings within the application.

Once a Terminal-instance has been created with a TerminalSettings-instance, the settings can not be changed anymore. Changes to the TerminalSettings-instance will be ignored.

The network and guides configuration as well as the configuration file are explained in the following chapters. For further information refer to TerminalSettings.

Follow these basic steps for using the TIM API:

1. Create TerminalSettings and initialize connection parameters (see Setup Configuration)
2. Create Terminal instance using the created TerminalSettings
3. Set some properties where required:
   • Define a POS ID
   • create mandatory list of EcrInfo and add with addEcrData
   • create list of PrintOptions and set with setPrintOptions
   • addListeners
4. Connect and Login. This can be done automatically, when the first terminal operation is called or manually using the login method.
5. Use terminal operation functions.

A basic flow to perform a transaction is:

The TIM API uses two different types of automatisms:

• Pre-Automatisms: This means that all actions that need to be done before a function can be called. E.g. 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 before the transaction is performed. The Pre-Automatisms are enabled by default.

• Post-Automatisms: These automatisms can be enabled or disabled using the members autoCommit and fetchBrands. A Post-Automatism is triggered after an action has been performed. E.g. if a connect has been called and fetchBrands is activated, an applicationInformation request is called automatically after the connect. Or if autoCommit is activated a commit is performed automatically after a transaction has been made. AutoCommit and fetchBrands are enabled by default.

The following diagramsshow the principle of the Pre-Automatisms and Post-Automatisms. Pre-Automatisms are enabled by default and cannot be disabled. If an error occurs the started request from the ECR is returned with an error.

Synchronous flow

Asynchronous flow

This chapter describes various guides and their use cases.

Hint: if no content visible, try to select a guide under "Guide Selection" on the left.

The basic operation modes of terminal method calls are:

1. Synchronous
   Method calls are blocking and return after the operation is finished successfully or throw a TimException otherwise. Please not that it is highly discouraged to use synchronous method calls on mobile platforms like Android because the main thread will be blocked by a synchronous call which may not be tolerated by the platform, as they are quite strict regarding blocking calls. This may result in a crash of the mobile App.

2. Asynchronous
   Method returns immediately after the operation has started or throws a TimException otherwise. A listener-event-method will be called after the operation is finished successfully. All listener-event-methods contain a TimEvent. In case of failure a TimException is included. User-implemented listener-handlers can be added to the Terminal-instance with addListener.

Functions called on terminal perform synchronous by default. The asynchronous method has the same name with Async appended to its name.

Code example for adding a terminal listener:

/** Asynchronous listener handling terminal events. */
class MyTerminalListener extends com.six.DefaultTerminalListener {

/* Overwrite all required methods from the DefaultTerminalListener class
 * herein which you want to use.
*/
}

// Create a new instance of the implemented MyTerminalListener
// class which then can be added to existing terminal object to handle
// the events that you've implemented.
terminal.addListener(new MyTerminalListener());

This chapter describes various flows for specific guides.

Hint: if no content visible, try to select a guide under "Guide Selection" on the left.

The TIM API is able to log an extensive set of events and actions within the TIM API. It's key that logs are created and stored properly. Logging enables support and makes bug-tracking much easier.

This chapter contains example implementations for TIM API.

A simple implementation using synchronous calls looks like this:

package simpletransaction;

import com.six.timapi.Terminal;
import com.six.timapi.TerminalSettings;
import com.six.timapi.TimException;
import com.six.timapi.constants.TransactionType;
import com.six.timapi.Amount;
import com.six.timapi.Receipt;
import com.six.timapi.constants.Currency;
import com.six.timapi.TransactionResponse;

import java.util.logging.Handler;
import java.util.logging.Level;
import java.util.logging.Logger;

public class SimpleTransaction {

    public static void main(String[] args) {

        // Create initial terminal settings
        TerminalSettings settings = new TerminalSettings();

        // Define terminal ID for default connection mode BROADCAST
        settings.setTerminalId("12345678");

        // Define log directory
        settings.setLogDir("C:\\Temp");

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

        // The logging level can be adjusted as follows, after the terminal object has been created.
        // The standard Java logging levels are valid
        Logger.getLogger(terminal.getLoggerName()).setLevel(Level.ALL);

        // By default, the logger has a FileHandler for logging into a file. The logging level that shall be
        // used for the file logging can be adjusted as follows.
        for (Handler handler : Logger.getLogger(terminal.getLoggerName()).getHandlers())
        {
            handler.setLevel(Level.FINEST);
        }

        try{
            // Start transaction. Automatically connects to and activates the terminal
            TransactionResponse trxResponse = terminal.transaction(TransactionType.PURCHASE, new Amount( 14.00,
            Currency.CHF));

            // If successful
            System.out.println("Transaction successful");

            // Both cardholder and merchant receipt are returned
            for(Receipt receipt : trxResponse.getPrintData().getReceipts()) {
                System.out.println(receipt.getRecipient() + receipt.getValue());
            }
        }

        catch (TimException te) {
            System.out.println("Transaction failed, exception: " + te.toString() );
        }

        catch (Exception se) {
            System.out.println("Systemexception: " + se.getMessage());
        }
    }
}

The same example as above but using asynchonous calls can look as follows:

import com.six.timapi.Terminal;
import com.six.timapi.TerminalSettings;
import com.six.timapi.Amount;
import com.six.timapi.constants.TransactionType;
import com.six.timapi.constants.Currency;

import javax.swing.*;

class ECRSample {
    public static void main(String [] args) {
        // Create terminal settings as described in the example above!
        TerminalSettings trmSettings = new TerminalSettings();

        // Create terminal instance using the communication settings. These settings can
        // not be changed anymore at a later time.
        Terminal terminal = new Terminal(trmSettings);

        // Set properties affecting the next login and transaction process. Changing POS-ID
        // has no effect until the next logout-login. Changing User-ID affects the next
        // transaction initiated
        terminal.setPosId("POS1234");
        terminal.setUserId(12345678);

        // Add the notifiers you wish to handle.
        // It can be done by adding a subclass of six.timap.TerminalNotifier as follows:

        // Add activateCompleted, transactionCompleted, commitCompleted, deactivateCompleted
        // and balanceCompleted notifier if required.
        terminal.addListener(new TerminalListener() {
            @Override
            public void activateCompleted(TimEvent e, ActivateResponse data) {
                // my code to be called if a activate request completed.
            }

            @Override
            public void transactionCompleted(TimEvent e, TransactionResponse data) {
                // my code to be called if a transaction request completed.

                // After the transaction request is completed correctly, a commit can be performed.
                // Only required if AutoCommit is not enabled.
                SwingUtilities.invokeLater(new Runnable() {
                    public void run() {
                        terminal.commitAsync();
                    }
                });
            }

            @Override
            public void commitCompleted(TimEvent e) {
                // my code to be called if a commit request completed.

                // A deactivateAsync() can be called here. This is not required if the option
                // AutoDeactivate is enabled, it will then be performed automatically.
                SwingUtilities.invokeLater(new Runnable() {
                    public void run() {
                        terminal.deactivateAsync()
                    }
                });

                // If AutoDeactivate is enabled, a balanceAsync() can be called directly and a
                // deactivation will be performed automatically.
                SwingUtilities.invokeLater(new Runnable() {
                    public void run() {
                        terminal.balanceAsync()
                    }
                });
            }

            @Override
            public void deactivateCompleted(TimEvent e, DeactivateResponse data) {
                // my code to be called if a deactivate request completed.
            }

            @Override
            public void balanceCompleted(TimEvent e, BalanceResponse data) {
                // my code to be called if a balance request completed.
            }
        });


        // Start a transaction process
        // If the terminal is not yet logged in or activated this two actions are performed
        // automatically before performing the transaction.
        terminal.transactionAsync(TransactionType.PURCHASE, new Amount(12.50, Currency.CHF));

        // If the option AutoCommit is enabled the commitAsync() method is called automatically
        // after the transaction has finished.
        // If not enabled, the commitAsync() method shall be called after receiving the
        // transactionCompleted event.

        // If the commit request is completed correctly the deactivate can be started
        // (see commitCompleted method). If the AutoDeactivate option is enabled a deactivateAsync()
        // is not required to be called. Another request that need a Deactivated state will then
        // perform a deactivateAsync() automatically. Otherwise the deactivateAsync() method can
        // be called after a successful commitCompleted event.

        // So if AutoDeactivate is enabled, a balanceAsync() can be called directly.
        // This can be done e.g. in the commitCompleted event (see commitCompleted event).
    }
}

Attention: Events are send from inside a thread different than the main thread. If you need to access code in the event handling thread use something like java.awt.EventQueue.invokeLater or javax.swing.SwingUtilities.invokeLater