go to Simple Implementation Guide
Detailed Implementation Guide

 Introduction

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.


 System Requirements

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)

 Setup Configuration

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.
The settings defined in the .cfg file will be overwritten by the changes done using the API code directly.

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.

 Network Configuration

Depending on the platform used, the TIM API module can communicate with the Terminal over different communication channels.

The default communication is over TCP/IP connection. Default port used is 7784.

On mobile devices also a Bluetooth connection is possible.

For TCP/IP connection there are two possible ways to connect to the terminal:

  • Broadcast-Mode:
    • Terminal ID (TID) is known.
    • The TIM API starts broadcasting on the default interface and connects to the connection information sent by the matching terminal.
  • Direct Connect:
    • IP address of the terminal is known.
    • Connection is established directly via IP.

 Guides Configuration

There are various Guides covering different use case scenarios. The guide Retail is the basic guide and is activated as default. With setGuides the guides can be configured. Important: the configuration needs to include all desired guides (including the retail guide).

Code-example for creating a terminal including settings with activated guides retail and hospitality:

// Create settings with Terminal-ID of terminal to connect to
com.six.TerminalSettings settings = new com.six.TerminalSettings();
settings.setTerminalId("12345678");

// add wanted guides (with bitwise or)
settings.setGuides(EnumSet.of(Guides.RETAIL, Guides.HOSPITALITY));

// Create terminal
com.six.Terminal terminal = new com.six.Terminal(settings);

//...

// Disconnect from terminal and clean up properly
terminal.dispose();

 Configuration File

With the use of the configuration file “TimApi.cfg” TerminalSettings can be set from outside of the application. If the user wishes to use multiple instances of the Terminal class it can be configured using ini-sections in the config file which are separated with a user defined DeviceId. The same DeviceId has to be used in the constructor of the TerminalSettings class if the specified configuration is wished to use. If no DeviceId is specified the global ini-section is used.

The precedence of the configuration is as follows:

  1. TimApi.cfg will be read first by creating a TerminalSettings object
  2. The config previously read from the TimApi.cfg file can be overwritten by hand using setter methods from the TerminalSettings class.

Table with Configuration File Parameters:

Parameter Description
LogDir Directory where log files are generated
LogLevel Logging level, defines how much information will be logged. For detailed values see Logging / LogLevel
LogRetainFileCount Defines how many log files will be kept before deleting (or archiving) to oldest. Logging / Log Rotation Handling
TerminalId Terminal ID to be broadcasted in case of ConnectionMode Broadcast
ConnectionMode Connection mode used between ECR and EFT. For more information see ConnectionMode
ConnectionIPString IP address of the EFT terminal in case of ConnectionMode OnFixIP and Websockets.
ConnectionIPPort Listening Port of the EFT terminal in case of ConnectionMode OnFixIP and Websockets.
SerialPort Serial port to be used for serial connection in case of ConnectionMode Serial.
SerialBaudrate Baudrate used in case of ConnectionMode Serial.
ProtocolType Protocol type. For detailed values see ProtocolType.
FetchBrands Automatically retrieves application information during logging in. Default is on (value “On” or “Off”)
AutoCommit After executing the Transaction- function the API commits the transaction automatically. Default is on (value “On” or “Off”)
RequestRepetition Defines how many times a Commit or Rollback request is sent repeatedly, if the original request has been lost. (Default = 0, means disabled = no repetition)
EnableKeepAlive Defines if KeepAlive functionality shall be enabled or not. Default is on (value “On” or “Off”).
SecuredConnection Defines if the TCP/IP or Websocket connection shall be secured using TLS. Default is off (value “On” or “Off”).

Example “TimApi.cfg”: This example describes the TimApi.cfg file with a global ini-section and two different ini-sections for specific DeviceIds:

[global]
ProtocolType = SIXml
TerminalId = 21001234
LogDir = var/log

[MyDeviceId]
ProtocolType = SIXml
TerminalId = 12345678
LogDir = var/otherLog

[MySecondDeviceId]
ProtocolType = SIXml
TerminalId = 87654321
LogDir = var/yetAnotherLog
ConnectionMode = OnFixIp
ConnectionIPString = 192.168.1.13
RequestRepetition = 2

[MyThirdDeviceId]
ProtocolType = SIXml
TerminalId = 18000001
LogDir = var/yetAnotherLog
ConnectionMode = Serial
SerialPort = COM1
SerialBaudrate = 115200

[MyFourthDeviceId]
ProtocolType = SIXml
TerminalId = 18000004
LogDir = var/yetAnotherLog
ConnectionMode = Websockets
ConnectionIPString = 192.168.1.13
ConnectionIPPort = 80
SecuredConnection = On

 Operation Overview

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:
  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:

Operations overview

 Automatisms

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

Synchronous flow

Asynchronous flow

Asynchronous flow

 Use Cases

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.

 Manual Pan Key Entry

The TIM API offers the possibility to perform a Manual Pan Key Entry (MPKE) on ECR side, e.g. if no physical card is present. This can be done by setting the CardRef field in the TransactionDatacontainer present in the terminal instance.

This CardRef field must have the following format to reference a non-PCI PAN:

Example: "061234567801234567" : "06" is the prefix that defines the content type that follows (non-PCI PAN), "1234568701234567" is then the non-PCI PAN.

Important: The MPKE on the ECR is only allowed for non-PCI brands, otherwise the manual entry must only be performed on the PIN Pad.

 Guide Petrol Use Cases

Petrol functionality adds a number of additional methods, transaction types, containers (AdditionalInfoList, Basket) and container content (ProcessingDisposition) notifiers and flows tailored to the needs at petrol stations.

Petrol has the following basic use cases:

 Petrol Basket Handling

An essential part of the petrol use cases is the usage of the Basket container. This container is used to exchange information regarding purchased goods and fuel at a petrol station. It is important to know that the correctness of the content of the basket container lies within the responsibility of the ECR and/or the acquiring host, not of the TIM API or the terminal.

The Basket is sent from the ECR to the terminal, then from the terminal to the host. The host may adjust the content of the Basket depending on the card used for the transaction, therefore the Basket sent from ECR to terminal may differ from the Basket returned from terminal to ECR.

A Basket may be used with the following TransactionTypes:

  • Purchase
  • FinalizePurchase

To send a Basket within a request, the TransactionRequest must be created by the integrator and the Basket and its BasketItems must then be set in the TransactionRequest. The TransactionRequest is then used as parameter of the Transaction/ TransactionAsync function.

The following snippet shows how to do this in code:

// Create a TransactionRequest object which can then
// be sent in a transaction() or transactionAsync()
// function.
TransactionRequest request = new TransactionRequest();

// At least an amount has to be set
request.setAmount(new Amount(25000, Currency.CHF));

// Create a basket object which can then contain
// a list of BasketItems.
Basket basket = new Basket();

// Create as many BasketItems as required
BasketItem basketItem = new BasketItem();

basketItem.setItemId("1");
basketItem.setLoyaltyId("32165498752");
basketItem.setAmount(new Amount(1000, Currency.CHF));
basketItem.setItemQuantity(new ItemQuantity(15, 0, "ltr"));
basketItem.setTotalAmount(15000, Currency.CHF);
basketItem.setProdDescription("Diesel");

BasketItem basketItem2 = new BasketItem();

basketItem.setItemId("45");
basketItem.setAmount(new Amount(500, Currency.CHF));
basketItem.setItemQuantity(new ItemQuantity(20, 0, "pcs"));
basketItem.setTotalAmount(10000, Currency.CHF);
basketItem.setProdDescription("Sweets");

// Add the created BasketItems to the Basket
basket.getItems().add(basketItem);
basket.getItems().add(basketItem2);

// If all required BasketItems have been added to the
// Basket, the Basket itself can be added the 
// TransactionRequest.
request.setBasket(basket);

// The request can then be used in a transaction
terminal.transactionAsync(TransactionType.PURCHASE, request);

 Indoor - Online Card

Online cards are processed like a standard credit or debit payment card through an online system, no mather if it is a standard credit card or an oil company card. In the latter case however, depending on the exact brand rules, additional data must be supplied by the ECR system (usually the type of goods being purchased, see Basket) and may be collected form the cardholder (e.g. ID number) and sent on to the online system.

The data is also provided back to the ECR via the Basket and AdditionalInfoList containers.

An online system may decline parts of the purchase basket.

The transaction flow differs from the standard scenario in an additional way. To distinguish between online cards (this scenario) and offline cards (that scenario ) it is necessary to first initiate a card detection through an InitTransaction call.

This is an indoor scenario, i.e. takes place in an attended environment, usually a shop that is part of the petrol station. See this flow for reference.

 Outdoor - Online Card

Outdoor - Online Card is esentially the same scenario as above. The difference is that it takes place on an unattended terminal generally located at or near the petrol pump.

This scenario requires that exchange of goods for money is slightly altered. The new sequence of events is: check if sufficient funds are available, hand out goods, finalize the funds transfer after the final amount is known. This is supported through the transaction types PreAuthorization and FinalizePurchase.

This is an outdoor scenario, i.e. takes place in an unattended environment, usually at the petrol pump. See this flow for reference.

 Indoor - Offline Card

Offline cards are cards that are processed entirely by the ECR system. The EFT operates only as a card reader, display and keyboard for the ECR. The ECR recognises offline cards based on the ProcessingDisposition returned from InitTransaction.

After the completion of InitTransaction the ECR is responsible for all further interaction. For cardholder interaction a number of dialogs (part of the "Dialog" guide) can be used.

This is an indoor scenario, i.e. takes place in an attended environment, usually a shop that is part of the petrol station. See this flow for reference.

 Outdoor - Offline Card

Outdoor offline processing of cards does not differ from indoor online processing.

This is an outdoor scenario, i.e. takes place in an unattended environment usually at the petrol pump. See this flow for reference.

 Guide Unattended Use Cases

Unattended functionality is aimed at the needs of vending machines an similar devices. It adds additional methods, transaction types and flows.

Unattended has the following basic use cases:

 Use Case Partial Commit

This use case deals with vending machines that dispense multiple products. It uses the standard retail "Purchase" transaction function with a subsequent "Commit". Products are dispensed after the successful transaction and before "Commit" is invoked. If only a part of the products can by dispensed (e.g. out of paper state on a ticketing machine) the cardholder should only be debited for the products actually received. To facilitate this commits can be "partial" meaning only an amount lower than the previously authorised amount is booked. To this end the commit-function has an amount parameter. See this flow for reference.

 Use Case Hold Commit

Products are usually dispensed between the successful transaction return and before "Commit" is invoked. Should product dispensing take more time than the commit timeout the timneout can be prolonged by HoldCommit. See this flow for reference.

 Use Case Amount Adjustment

Some machines allow the cardholder to buy multiple products, each product operation changing the final amount to pay. These machines may also choose to allow the cardholder to finalize the purchase by just inserting the credit card instead of pressing an additional button. For contactless support the terminal needs to always be ready for a transaction, therefore the transaction amount needs to be continualy updated. This can be achived with "Amount Adjustment". See this flow for reference.

 Use Case Retain Card

A vending machine has the option to prevent the automatic ejection of the card right after the transaction and instead opt to handle the exact ejection time itself. This is achived with the "Retain Card"-flag See this flow for reference.

 Use Case Silent Abort

Machines that take multiple forms of payment (e.g. cash and cards) will often open all payment channels. If the customer chooses a payment means not handled by the terminal the terminal transaction needs to be aborted. Usually this shows "Abort" on the screen of the terminal which can be confusing the the customer. Therefore it is possible to do a "silent abort" that prevents that text from appearing. See this flow for reference.

 Guide Banking Use Cases

Banking functionality adds an additional method, banking transaction types, notifiers and flows tailored to the needs of banking use cases.

Banking guide offers the following use cases:

 Balance Inquiry

To have an overview about the balance of the account, TIM offers a function to check the current account balance of the card used. This function is called BalanceInquiry and requires a present card. To be sure that only the right cardholder is able to check his/her account balance a PIN check will be performed.

See this flow for reference.

 Client Identification

For certain banking actions it is required to identify the cardholder by performing a PIN check. TIM offers this functionality using the "Dialog Mode" which requires the "Dialog" guide as well, besides the "Banking" guide. The corresponding value for ResourceId used to show a PIN check dialog is PinCheck.

See this flow for reference.

 Signature Capture

Besides checking the PIN of a customer it may be required that a customer has to sign to perform a certain action. TIM offers a signature capture functionality. This function requires the "Dialog" guide to be active, besides the "Banking" guide, if used in banking environment. The corresponding function ShowSignatureCapture is shown more detailed in the "Dialog" guide.

See this flow for reference.

 Card Identification

As there might be some special cards used in the banking environment and therefore special functions used, TIM allows to make a card identification which delivers CardData to determine which action should be done next, depending on the card data returned. This function requires the "Dialog" guide to be active, besides the "Banking" guide. The corresponding values for ResourceId used to identify the card used, are either Swiss Post CardIdentification for Swiss Post or Banking CardIdentification for other Banking purposes.

See this flow for reference.

 Account Transfer: Swiss Post only

A common use case at a bank is to transfer money from one account to another. To be able to use this feature the "Dialog" guide is required besides the "Banking" guide. TIM offers a function that allows to set the source account, the destination account and the amount to transfer. The function ShowDialogAsync with the corresponding ResourceId and the PlaceholderItems must be used. The correct ResourceId is InterAccountTransfer and the following PlaceholderItems are required to be set in the ShowDialogRequest:

  • 0: Source Account
  • 1: Source Account Type
  • 2: Currency Source Account
  • 3: Source Account - Description
  • 4: Destination Account
  • 5: Destination Account Type
  • 6: Currency Destination Account
  • 7: Destination Account - Description
  • 8: Currency
  • 9: Amount

See this flow for reference.

 Account Deposit: Swiss Post only

Another use case is that the customer wants to deposit an amount on his/her account. To be able to use this feature the TransactionType "AuthorizeDeposit" is introduced in the "Banking" guide. This is done with the function TransactionAsync and the corresponding TransactionType.

See this flow for reference.

 Account Payout: Swiss Post only

A similar use case as above is that the customer wants to withdraw an amount from his/her account. To be able to use this feature the "Dialog" guide is required besides the "Banking" guide. This is also done with the function ShowDialogAsync and the corresponding ResourceId and PlaceholderItems. The correct ResourceId is DisbursementFromAccount and the following PlaceholderItems are required to be set in the ShowDialogRequest:

  • 0: Debit Account
  • 1: Debit Currency
  • 2: Amount

See this flow for reference.

 Parcel Acknowledgement: Swiss Post only

This next use case is that a customer wants to pick up a parcel and must sign on the device to acknowledge that he/she actually picked up the parcel. As this requires the signature input of the customer it is offered as dialog function ShowDialogAsync and the corresponding ResourceId. This requires an activeted "Dialog" guide. The correct ResourceId is PacketAcknowledgement, There are no PlaceholderItems required.

See this flow for reference.

 Load PrePaid Phone: Swiss Post only

Another use case is to load a pre paid phone. This is also done with the function ShowDialogAsync and the corresponding ResourceId and PlaceholderItems. The correct ResourceId is ShowPhoneNumberWithAmount and the following PlaceholderItems are required to be set in the ShowDialogRequest:

  • 0: Phone number
  • 1: Currency
  • 2: Amount to load

See this flow for reference.

 Guide Austrian Use Cases

The Austria guide adds two new use cases:

  • Non guaranteed payment (NGV)
  • Delayed payment

Both use cases do not add any new functions. Only the standard TransactionAsync and Transaction functions with TransactionType Purchase are used with additional parameters the can be set in TransactionData before starting the purchase transaction.

 Austrian Use Case: NGV

An NGV payment is used in conjunction with a standard purchase transaction. The difference is that the purchase is handled as an own risk transaction for the merchant. Before starting a purchase transaction the NGVMode can be set according to NGVMode to define the NGV behaviour of a transaction.

With the NGVMode it is possible to either forbid NGV usage for the next transaction, to allow it with a fallback to a standard purchase transaction or to set NGV usage to mandatory.

  • If the NGV usage is explicitly forbidden the purchase transaction must be performed as a standard purchase.
  • If the NGV is wished but fallback is allowed it is possible that the current purchase will either be performed as an NGV purchase or automatically as a standard purchase in case it is not possible to make an NGV purchase.
  • If NGV usage is set to mandatory the current purchase transaction must be performed as an NGV purchase. If this is not possible the purchase transaction fails without fallback.

To identify if the current transaction has been performed as an NGV purchase or not a new boolean flag NGVUsedFlag has been introduced in the TransactionResponse. For statistics the NGV transactions can also be identified in the Counters using the same NGVUsedFlag.

 Austrian Use Case: Delayed Payment

The delayed payment can only be used in conjunction with an NGV purchase. For delayed payments, the clearing of a transaction is delayed by the clearing house for the defined number of days. The delay is set using the ClearingDelay member in TransactionData.

 Terminal methods overview

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

 Main / guide Retail terminal functions

Sync method
Async method
Completed event
Description
activate
activateAsync
activateCompleted
Open a user shift.
applicationInformation
applicationInformationAsync
applicationInformationCompleted
Request the list of brands available on the terminal.
balance
balanceAsync
balanceCompleted
Force the EFT Terminal to transmit all transactions to the
host system as well to do the daily closing.
cancel Aborts an open asynchronous Financial Transaction or Non-Financial Transaction request, except for a commit or rollback request, which cannot be cancelled.
changeSettings
changeSettingsAsync
changeSettingsCompleted
Change configuration parameters of the EFT Terminal.
commit
commitAsync
commitCompleted
Perform Commit-operation after a successful Transaction call.
connect
connectAsync
connectCompleted
Initiates a connection to the EFT Terminal.
counterRequest
counterRequestAsync
counterRequestCompleted
Get counter information`s from the EFT Terminal.
dccRates
dccRatesAsync
dccRatesCompleted
Request DCC rates from the EFT Terminal.
deactivate
deactivateAsync
deactivateCompleted
Close a user shift.
disconnect
disconnectAsync
disconnected
Interrupts the connection to the EFT Terminal.
hardwareInformation
hardwareInformationAsync
hardwareInformationCompleted
Get hardware information from the EFT Terminal.
login
loginAsync
loginCompleted
Activate a communication session between the ECR and
the terminal.
logout
logoutAsync
logoutCompleted
Terminate an active communication session between the ECR
and the terminal.
reboot
rebootAsync
rebootCompleted
Force the EFT Terminal to reboot.
receiptRequest
receiptRequestAsync
receiptRequestCompleted
Receive the latest receipt or a list of silent receipts.
reconciliation
reconciliationAsync
reconciliationCompleted
Force the EFT Terminal to transmit all financial transactions
to the host system.
reconfig
reconfigAsync
reconfigCompleted
Force the EFT Terminal to get the configuration from the service center.
rollback
rollbackAsync
rollbackCompleted
Prevent a transaction from being committed to the transaction
log and generates a technical reversal of the authorization.
softwareUpdate
softwareUpdateAsync
softwareUpdateCompleted
Force the EFT Terminal to start a Software Update.
systemInformation
systemInformationAsync
systemInformationCompleted
Request system information from the EFT Terminal.
transaction
transactionAsync
transactionCompleted
Starts an EFT Terminal Transaction.

 Guide Petrol terminal functions

Sync method
Async method
Completed event
Description
initTransaction
initTransactionAsync
initTransactionCompleted
Retrieve card data for the presented card.

 Guide Unattended terminal functions

Sync method
Async method
Completed event
Description
openReader
openReaderAsync
openReaderCompleted
Opens the shutter of the card reader.
amtAdjustment Send an amount adjustment notification to the terminal during an open transaction. The amount is used as the new amount for the transaction.
closeMaintenanceWindow
closeMaintenanceWindowAsync
closeMaintenanceWindowCompleted
Prohibits the EFT terminal from performing any triggered maintenance tasks.
closeReader
closeReaderAsync
closeReaderCompleted
Closes the shutter of the card reader.
commit
commitAsync
commitCompleted
Commits a transaction after succesful authorization. A lower amount may be commited than the authorized amount.
ejectCard
ejectCardAsync
ejectCardCompleted
Ejects the card from the card reader.
holdCommit Increases the commit timeout.
openMaintenanceWindow
openMaintenanceWindowAsync
openMaintenanceWindowCompleted
Opens a maintenance window where the terminal can perform all maintenance processes it was not able to perform before.>

 Guide Dialog terminal functions

Sync method
Async method
Completed event
Description
openDialogMode
openDialogModeAsync
openDialogModeCompleted
Open dialog mode on the terminal.
closeDialogMode
closeDialogModeAsync
closeDialogModeCompleted
Close dialog mode on the terminal.
showDialog
showDialogAsync
showDialogCompleted
Show dialog on the terminal.
showSignatureCapture
showSignatureCaptureAsync
showSignatureCaptureCompleted
Show signature capture on the terminal.

 Additional terminal listener-events

Listener-event Description
requestCompleted Operation started by an asynchronous function has finished.
Applications can use both operation specific completion callback
in combination with this generic completion callback.
terminalStatusChanged The terminal status has changed. The new status can be
retrieved from the TerminalStatus property.

 Flows

This chapter describes various flows for specific guides.

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

 Petrol Additional Flows

 Petrol Flow: Indoor - Online Card

ECRECREFTEFTClientClientHostHostTransactionState: IdleInit Transaction Request (Amount)TransactionState: WaitForCardInsert CardStart reading cardTransactionState: ReadingCardTransactionState: ApplicationSelectionHave read all card dataTransactionState: WaitForProceedInit Transaction Response ([CardData], [ProcessingDisposition=OnEFT])Purchase Request ([Basket], Amount)opt[MOC Petrol: AdditionalInformation already required in AuthRequest]loop[0..n]Request additional informationEntry additional informationAuthorization Request (Amount, [AddInfo], [SetOfRestrictions])Authorization Response (Amount, [AddInfo], [SetOfRestrictions])opt[MOC Online: AdditionalInformation only required in submission]loop[0..n]Request additional informationEntry additional informationopt[Amount may have changed: Cardholder confirmation]Confirm new amountPurchase Response (Amount, [AdditionalInfo], [Basket], [PrintData], TransactionInformation)Commit RequestCommit Response

 Petrol Flow: Outdoor - Online Card

ECRECREFTEFTClientClientHostHostInit Transaction RequestTransactionState: WaitForCardInsert CardStart reading cardTransactionState: ReadingCardTransactionState: ApplicationSelectionHave read all card dataTransactionState: WaitForProceedInit Transaction Response ([CardData], [ProcessingDisposition=OnEFT])PreAuth Request (Amount)opt[MOC Petrol: AdditionalInformation already required in AuthRequest]loop[0..n]Request additional informationEntry additional informationAuthorization Request (Amount, [AddInfo], [SetOfRestriction])Authorization Response ([AddInfo], [SetOfRestrictions])opt[MOC Online: AdditionalInformation only required in submission]loop[0..n]Request additional informationEntry additional informationPreAuth Response ([AdditionalInfo], [Basket], Amount)opt[At ECR Discretion]OpenDialogMode RequestOpenDialogMode Responseloop[0..n]Dialog mainly used for pump selection and the like.Dialog RequestRequest additional informationEntry additional informationDialog ResponseCloseDialogMode RequestCloseDialogMode ResponsePump selectedRemove cardPump petrolFinalizePurchase Request ([AdditionalInfo], [Amount], [TransactionData], [Basket])loop[1..3]Online Advice Request (Amount, [AddInfo], [SetOfRestrictions])Online Advice Response (Amount, [AddInfo], [SetOfRestrictions])FinalizePurchase Response (Amount, [Basket], [PrintData], TransactionInformation)Commit RequestCommit Response

 Petrol Flow: Indoor - Offline Card

ECRECREFTEFTClientClientHostHostInit Transaction Request (Amount)TransactionState: WaitForCardInsert CardStart reading cardTransactionState: ReadingCardTransactionState: ApplicationSelectionHave read all card dataTransactionState: IdleInit Transaction Response ([CardData], [ProcessingDisposition=OnECR])OpenDialogMode RequestOpenDialogMode Responseloop[0..n]Dialog RequestRequest additional information- Collection of FleetID, Mileage, UserID.- PIN check- Pump selectionEntry additional informationDialog ResponseDialog Request ([RemoveCard])Show "Please Remove card"Takes cardDialog ResponseCloseDialogMode RequestCloseDialogMode Response

 Petrol Flow: Outdoor - Offline Card

ECRECREFTEFTClientClientHostHostInit Transaction RequestTransactionState: WaitForCardInsert CardStart reading cardTransactionState: ReadingCardTransactionState: ApplicationSelectionHave read all card dataTransactionState: IdleInit Transaction Response ([CardData], [ProcessingDisposition=OnECR])OpenDialogMode RequestOpenDialogMode Responseloop[0..n]Dialog RequestRequest additional information- Collection of FleetID, Mileage, UserID.- PIN check- Pump selectionEntry additional informationDialog ResponseDialog Request ([RemoveCard])Show "Please Remove card"Takes cardDialog ResponseCloseDialogMode RequestCloseDialogMode Response

 Guide Unattended Additional Flows

  Flow: Partial Commit

ECRECREFTEFTClientClientHostHostTerminalTerminalPurchase(Amount, TransactionData)InsertCard / TapCardPinEntryCardRemoval (for Contact)return Purchase(ResultCode = 0)TransactionState: WaitForCommitalt["Partial Commit" if Vending Machine failed to deliver all goods]Commit(Amount)["Commit" no discount]Commit()return Commit()

  Flow: Hold commit

ECRECREFTEFTClientClientHostHostTerminalTerminalPurchase(Amount, TransactionData)InsertCard / TapCardPinEntryCardRemoval (for Contact)return Purchase(ResultCode = 0)opt["Vending Machine busy"]loop["SendingHoldCommitnotifications as long as Vending Machine is not ready to continue."]HoldCommit()Commit()return Commit()

  Flow: Amount adjustment

ECRECREFTEFTClientClientHostHostTerminalTerminalPurchase(Amount, TransactionData)loopSelect ItemAmtAdjustment(Amount)TerminalStatusNotification(FinalAmount)InsertCard / TapCardPinEntryCardRemoval (for Contact)return Purchase(ResultCode = 0)Commit()return Commit()

  Flow: PreAuthorization

ECRECREFTEFTClientClientHostHostTerminalTerminalPreAuthorization(Amount, TransactionData)InsertCard / TapCardPinEntryCardRemoval (for Contact)return PreAuthorization(ResultCode = 0)Vending Machine dispensing goods.FinalizePurchase()return FinalizePurchase()alt[If AutoCommit diabled]Commit()return Commit()

  Flow: Retain card

ECRECREFTEFTClientClientHostHostTerminalTerminalPurchase()Terminal display:EUR 23.50Card pleaseInsertCard / TapCardalt[CardRetainFlag = true]Cancel(CardRetainFlag = true)CardRetainFlag is used so thecard is retained insidethe card reader after the abort.Terminal display:Abort[CardRetainFlag = false]Cancel(CardRetainFlag = false)CardRetainFlag is NOT used so thecard is not retained insidethe card reader after the abort.Terminal display:Abortreturn Purchase(ResultCode = 50, ErrorMessage)Card is ejectedTerminal display:Remove card pleaseCard removal

  Flow: Silent abort

ECRECREFTEFTClientClientHostHostTerminalTerminalPurchase()Terminal display:EUR 23.50Card pleaseInsertCard / TapCardalt[Silent Abort]Cancel(SilentFlag = true)SilentFlag is used sothe terminal won't show"Abort" on its display.[No Silent Abort]Cancel(SilentFlag = false)SilentFlag is NOT used sothe terminal will show"Abort" on its display.Terminal display:Abortreturn Purchase(ResultCode = 50, ErrorMessage)Card will be ejected.

 Banking Additional Flows

 Banking Flow: BalanceInquiry

ECRECREFTEFTClientClientalt[Card before transaction]Card insertionBalanceInquiryAsync() requestalt[Card after transaction]Card insertionPIN entryalt[PIN wrong]loop[if PIN entered wrong and not last PIN try]PIN wrongTry againPIN & OKPIN entryalt[PIN wrong and last PIN try]PIN wrongLast tryPIN & OKPIN entryalt[Last PIN try wrong]BalanceInquiryCompleted() ResultCode != 0[PIN correct]PIN OKBalanceCHF 2000.00BalanceInquiryCompleted() ResultCode = 0

 Banking Flow: Client Identification

ECRECREFTEFTClientClientalt[Card before transaction]Card insertionalt[Swiss Post]ShowDialogAsync(ResourceId=PIN_ENTRY) request[Banking]ShowDialogAsync(ResourceId=BANKING_PIN_CHECK) requestalt[Card after transaction]Please insert cardCard insertionPIN & OK_ _ _ _ _ _PIN entryalt[PIN wrong]loop[if PIN entered wrong and not last PIN try]PIN wrongTry againPIN & OKPIN entryalt[PIN wrong and last PIN try]PIN wrongLast tryPIN & OKPIN entryalt[Last PIN try wrong]ShowDialogCompleted() Reason=PIN_NOK[PIN correct]PIN OKShowDialogCompleted() Reason=PIN_OK

 Banking Flow: Card Identification

ECRECREFTEFTClientClientalt[Swiss Post]ShowDialogAsync(ResourceId=WELCOME_CARD) request[Banking]ShowDialogAsync(ResourceId=BANKING_INSERT_CARD) requestWelcome, card pleaseCard insertionReading cardShowDialogCompleted() CardData, Reason=CardReader

 Banking Flow: Account Transfer

ECRECREFTEFTClientClientShowDialogAsync(ResourceId = INTER_ACCOUNT_TRANSFER, PlaceholderItems) requestFrom 01-234567-8 Sparkonto CHFMax, Mustermannto 09-876543-2 Privatkonto CHFMax, MustermannCHF 10.00alt[STOP by cardholder]Cardholder input: STOPShowDialogCompleted() Reason=STOP[OK]Cardholder input: OKShowDialogCompleted() Reason=OKShowDialogAsync(ResourceId = INTER_ACCOUNT_TRANSFER_CONFIRMATION, PlaceholderItems) request01-234567-8 Sparkonto CHFCHF 1234.5609-876543-2 Privatkonto CHFCHF 4321.56alt[STOP by cardholder]Cardholder input: STOPShowDialogCompleted() Reason=STOP[OK]Cardholder input: OKShowDialogCompleted() Reason=OK

 Banking Flow: Account Deposit

ECRECREFTEFTClientClientCard insertionTransactionAsync(TransactionType = AuthorizeDeposit, Amount) requestalt[Card after transaction]Please insert cardCard insertionDeposit own accountauthorizationCHF 10.00 OK?alt[STOP by cardholder]STOP pressedTransactionCompleted() ResultCode != 0[OK by cardholder]OK pressedTransactionCompleted() ResultCode = 0

 Banking Flow: Account Payout

ECRECREFTEFTClientClientShowDialogAsync(ResourceId = DISBURSEMENT_FROM_ACCOUNT, PlaceholderItems) requestDisbursement from account01-2345-6CHF 10.00 OK?alt[STOP by cardholder]Cardholder input: STOPShowDialogCompleted() Reason=STOP[OK]Cardholder input: OKShowDialogCompleted() Reason=OK

 Banking Flow: Parcel Acknowledgement

ECRECREFTEFTClientClientShowSignatureCaptureAsync(ResourceId = PACKET_ACKNOWLEDGEMENT) requestI acknowledge havingreceived the parceland its listed contents:Signature please:_ _ _ _ _ _ _ _ _ _alt[Client signs on terminal]Input signatureCardholder input: OKShowSignatureCaptureCompleted() Reason=OK[Client STOP]Cardholder input: STOPShowSignatureCaptureCompleted() Reason=STOP

 Banking Flow: Load PrePaid Phone

ECRECREFTEFTClientClientShowDialogAsync(ResourceId = ENTER_PHONE_OR_PREPAID_NUMBER) requestEnter phone numberor Prepaid card:_ _ _ _ _ _ _ _ _ _alt[Client presses STOP]STOP pressedShowDialogCompleted() Reason=STOP[Client enters phone number and presses OK]Input phone numberCardholder input: OKShowDialogCompleted() Reason=OK[Cardholder inserts card]Card insertionShowDialogCompleted() Reason=CardReaderalt[In case of OK or card insertion]ShowDialogAsync(ResourceId = SHOW_PHONE_NUMBER, PlaceholderItems) requestYour phone number012 345 67 89alt[Cardholder STOP]STOP pressedShowDialogCompleted() Reason=STOP[Cardholder OK]OK pressedShowDialogCompleted() Reason=OKShowDialogAsync(ResourceId = SHOW_PHONE_NUMBER_WITH_AMOUNT, PlaceholderItems) request012 345 67 89CHF 50.00alt[Cardholder STOP]STOP pressedShowDialogCompleted() Reason=STOP[Cardholder OK]OK pressedShowDialogCompleted() Reason=OKShowDialogAsync(ResourceId = PROCESSING_OK) requestShowDialogCompleted() Reason=OK

 Guide Austrian Additional Flows

 Austrian Flow: NGV Purchase without delay

The following flow describes an NGV purchase without any specific clearing delay set. The NGVMode "AllowedWithFallback" is used which indicates it the card used is not capable of NGV payments the terminal is allowed to make a fallback to a standard purchase. This flow shows a successfully performed NGV payment which can be seen by checking the value NGVUsedFlag, which is set to "true".

ECRECRTimApiTimApiTerminalTerminalAcquirerAcquirerSet NGVMode = "AllowedWithFallback" in TransactionDataTransaction request (TransactionType = Purchase, Amount)FinTransaction:Purchase (Amount, TransactionData)The terminal checks if the cardused is capable of an NGV paymentand performs it if check has beensuccessful.opt[Maybe no authorization can be made]Authorization requestAuthorization responseTransaction response (ResultCode = 0, NGVUsedFlag = true)Transaction response (TransactionResponse[ResultCode, TransactionInformation, ...])Get NGVUsedFlag from TransactionInformation to determine if NGV was successfulAs no ClearingDelay has been setin TransactionData for this transaction,the clearing house will do the clearing as usual,without a specially defined delay.

 Austrian Flow: NGV Purchase with delay

In the flow below, additionally to the NGVMode "AllowedWithFallback" also the ClearingDelay is set to define a specific clearing delay in days. This means that the NGV payment clearing will be delayed by the amount of days specified. This flow shows a successful NGV payment including a clearing delay.

ECRECRTimApiTimApiTerminalTerminalAcquirerAcquirerSet NGVMode = "AllowedWithFallback" in TransactionDataSet ClearingDelay in TransactionDataTransaction request (TransactionType = Purchase, Amount)FinTransaction:Purchase (Amount, TransactionData)The terminal checks if the cardused is capable of an NGV paymentand performs it if check has beensuccessful.opt[Maybe no authorization can be made]Authorization requestAuthorization responseTransaction response (ResultCode = 0, NGVUsedFlag = true)Transaction response (TransactionResponse[ResultCode, TransactionInformation, ...])Get NGVUsedFlag from TransactionInformation to determine if NGV was used successfullyThe clearing house will do theclearing of the transactionafter the defined delay.

 Austrian Flow: NGV Purchase fallback with Non-NGV card

The following flow describes an NGV payment with NGVMode "AllowedWithFallback" which results in a fallback to a standard purchase due to the fact that the card used is not capable of NGV payments. The NGVUsedFlag is used to determine if the NGV payment was performed as such or if a fallback was used. In this case the NGVUsedFlag value is set to "false" which indicates that the requested NGV payment was not successful and the fallback to a standard purchase has been done.

ECRECRTimApiTimApiTerminalTerminalAcquirerAcquirerSet NGVMode = "AllowedWithFallback" in TransactionDataTransaction request (TransactionType = Purchase, Amount)FinTransaction:Purchase (Amount, TransactionData)The terminal checks if the cardused is capable of an NGV paymentand performs it if check has beensuccessful.In this case the card used does notsupport NGV payments. Therefore the terminalmakes a fallback to a standard purchasetransaction, as NGVMode = "AllowedWithFallback"allows a fallback.Authorization requestAuthorization responseTransaction response (ResultCode = 0, NGVUsedFlag = false)As the NGVMode is set to"AllowedWithFallback" theTerminal made a fallbackto a standard purchase ifthe card used did notsupport NGV.Transaction response (TransactionResponse[ResultCode, TransactionInformation, ...])Get NGVUsedFlag from TransactionInformation to determine if NGV was used successfullyThe clearing house will do theclearing of the transactionas usual, as no special delayhas been defined.

 Austrian Flow: NGV Purchase mandatory with error

The following flow describes a mandatory NGV purchase transaction which could not be performed by the terminal. As the used NGVMode is "Mandatory" but the card used is not capable of NGV payments, the transaction results in an error which means a resultCode != '0' and an error payload as transaction response.

ECRECRTimApiTimApiTerminalTerminalAcquirerAcquirerSet NGVMode = "Mandatory" in TransactionDataTransaction request (TransactionType = Purchase, Amount)FinTransaction:Purchase (Amount, TransactionData)As NGVMode = "Mandatory" theTerminal must perform an NGV payment.If this is not possible thetransaction is returned with an error.opt[Maybe no authorization can be made]Authorization requestAuthorization responseTransaction response (ResultCode != 0, NGVUsedFlag = false)As the NGVMode is set to"Mandatory" theTerminal is NOT allowed tomake a fallbackto a standard purchase ifthe card used did notsupport NGV.Transaction response (TimException, Error Payload)

 Logging

 LogLevel

By default the TIM API has a Logger that defines how much logging is generated inside the TIM API. To this Logger different handlers can be added, e.g. ConsoleHandler for logging into the debug console or FileHandler to log into a file. By default a FileHandler is added to the TIM API logger.

The following logging levels are valid:

  • ALL
  • FINEST
  • FINER
  • FINE
  • CONFIG
  • INFO
  • WARNING
  • SEVERE
  • OFF

The logging level can be adjusted programatically as follows after a terminal object has been created:

// Set the TIM API internal logging level
Logger.getLogger(terminal.getLoggerName()).setLevel(Level.ALL);

// Set the logging level of the different handlers that have been added to the logger
Handler[] handlers = Logger.getLogger(terminal.getLoggerName()).getHandlers();

for (Handler handler : handlers){
    handler.setLevel(Level.FINEST);
}

// To add a special handler to the TIM API logger
Logger.getLogger(terminal.getLoggerName()).addHandler(myHandler);

 Log Rotation Handling

The TIM API allows to configure a log file rotation handling, which means that it can be defined how many log files should be kept before deleting or archiving them. Furthermore it can be defined how many log files are allowed in one archive and how many archives should be kept before deleting the oldest. To define this behaviour the following parameter can be used, which are located in TerminalSettings if they shall be set programatically. If not they can be also set in the TimApi.cfg file.

  • LogRetainFileCount: Defines how many log files will be kept before deleting (or archiving) the oldest.

  • LogFileCountPerArchive: Defines how many log files will be put in an archive before creating a new archive.

  • LogRetainArchiveCount: Defines how many archives will be kept before deleting the oldest. 0 = no archiving

The following diagram shows the log rotation handling process:
Log Rotation Handling Process

 Code Examples

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