Class: Terminal

timapi.Terminal(settings)

Terminal base implementation. Create instance of TerminalApi to connect to payment terminal.

Overview

Methods-Overview

Constructor

new Terminal(settings)

Create terminal from timapi.TerminalSettings
Parameters:
Name Type Description
settings timapi.TerminalSettings

Methods

activateAsync()

Opens a user shift. If the shift is already open, no error is returned.

Returns immediately and calls activateCompleted on all notifiers once finished.

activateServiceMenuAsync()

Activate service menu.

Returns immediately and calls activateServiceMenuCompleted on all notifiers once finished.

Note: This method is only available if guide unattended is enabled.

addEcrData(ecrInfo)

Add ECR data. Replaces ECR data of the same type, if already present.

To remove all elements use setEcrData instead.

Parameters:
Name Type Description
ecrInfo timapi.EcrInfo ecr information to add

addListener()

Register listener.
Throws:
  • IllegalArgumentException If listener is undefined.
  • IllegalArgumentException If listener is registered.

amtAdjustment(amount)

The AmtAjustment-function is used as a notification to dynamically adjust the transaction amount of an already running transaction. This is a "best effort" function and will be processed as long as the underlaying payment protocol supports it. The amount transmitted in the notification is the new total amount. The EFT does not calculate amounts, this is the ECRs responsibility.

To be able to validate if this notification has been processed correctly the TerminalStatus-notification returns the adjusted final amount.

Note: This method is only available if guide unattended is enabled.

Parameters:
Name Type Description
amount timapi.Amount New corrected amount

amtAdjustmentVas(amount, amountDiscount, loyaltyCouponList, loyaltyInformationList)

Dynamically adjusts the transaction amount and also provide additional loyalty information of an already running request. This is a "best effort" function and will be processed as long as the underlying payment protocol supports it. The amount transmitted in the notification is the new total amount. The EFT does not calculate amounts, this is the ECRs responsibility.

To be able to validate if this notification has been processed correctly the TerminalStatus-notification returns the adjusted final amount.

Note: This method is only available if guide valueAddedServices is enabled.

Parameters:
Name Type Description
amount timapi.Amount New corrected amount
amountDiscount timapi.AmountDiscount New discount amount
loyaltyCouponList Array.<timapi.LoyaltyCoupon> List of loyalty coupons
loyaltyInformationList Array.<timapi.LoyaltyInformation> List of loyalty information

applicationInformationAsync()

Requests the list of brands available on the terminal.

Returns immediately and calls applicationInformationCompleted on all notifiers once finished.

Side-Effect: Updates Brands member with all brands available on the terminal. Use getBrands to retrieve them.

balanceAsync()

Forces the EFT Terminal to transmit all transactions to the host system as well to do the daily closing.

Returns immediately and calls balanceCompleted on all notifiers once finished.

balanceInquiryAsync()

Get information about the current account balance of the inserted card.

Returns immediately and calls balanceInquiryCompleted on all notifiers once finished.

Note: This method is only available if guide advanced_retail is enabled.

cancel()

Aborts an open asynchronous Financial Transaction or Non-Financial Transaction request, except for a commitAsync or rollbackAsync request, which cannot be cancelled.

Further information: A Cancel-request is a best effort request. The EFT Terminal can ignore the Cancel-request if the request in progress is in a state it can not be cancelled. A Cancel-request has no effect if there's no open request of a Financial Transaction or Non-financial Transaction. If the EFT Terminal cancels the request in progress an error response is send back for the cancelled request (see chapter Abort Purchase for an example). Cancel-requests can be send multiple times in an attempt to cancel a request in progress but should be spaced by a few seconds. Cancel-requests themselves are never acknowledged by the EFT Terminal.

The Transaction request can only be cancelled before a Commit has been performed. Also the underlying payment protocol can restrict this functionality.

cancelUnattended(silent, retainCard)

Aborts an open asynchronous Financial Transaction or Non-Financial Transaction request, except for a commitAsync or rollbackAsync request, which cannot be cancelled.

Further information: A Cancel-request is a best effort request. The EFT Terminal can ignore the Cancel-request if the request in progress is in a state it can not be cancelled. A Cancel-request has no effect if there's no open request of a Financial Transaction or Non-financial Transaction. If the EFT Terminal cancels the request in progress an error response is send back for the cancelled request (see chapter Abort Purchase for an example). Cancel-requests can be send multiple times in an attempt to cancel a request in progress but should be spaced by a few seconds. Cancel-requests themselves are never acknowledged by the EFT Terminal.

The Transaction request can only be cancelled before a Commit has been performed. Also the underlying payment protocol can restrict this functionality.

Note: This method is only available if guide unattended or guide petrol is enabled.

Parameters:
Name Type Description
silent Boolean Will prevent the cancel from displaying any “abort”-messages to the cardholder
retainCard Boolean Will prevent the card from being ejected for later use by the Dialog Mode

canDcc() → {Boolean}

Returns true if at least one payment protocol and the terminal configuration offer DCC i.e. if there is a chance to do a DCC transaction.
Returns:
true if dcc is supported

Type: Boolean

canDeclinedReceipts() → {Boolean}

Support for "Declined Receipts" in at least one payment protocol.
Returns:
true if declined receipts are supported

Type: Boolean

canMultiAccountSelection() → {Boolean}

Support for multiple account selection
Returns:
true if multiple account selection is supported

Type: Boolean

changeSettingsAsync(settings)

Changes configuration parameters of the EFT Terminal.

Returns immediately and calls changeSettingsCompleted on all notifiers once finished.

Parameters:
Name Type Description
settings Map.<timapi.constants.SettingType, String> Dictionary of values for settings types to change.

closeDialogModeAsync()

Close dialog mode on the terminal.

Returns immediately and calls closeDialogModeCompleted on all notifiers once finished.

Note: This method is only available if guide dialog is enabled.

closeMaintenanceWindowAsync()

Closes the maintenance window to the terminal so it can perform collected maintenance requests on its own, without interaction with the ECR. The terminal shall respond immediately to the ECR request whether it is able to handle the request or not.

If the terminal is able to handle the request, the ECR is free itself to perform maintenance as well or it can monitor the terminal by reading the TerminalStatus notifications.

It is possible that the connection between ECR and EFT terminal is terminated due to one or multiple reboot processes.

Returns immediately and calls closeMaintenanceWindowCompleted on all notifiers once finished.

Note: This method is only available if guide unattended is enabled.

closeReaderAsync()

Close the shutter of the card reader.

Returns immediately and calls closeReaderCompleted on all notifiers once finished.

Note: This method is only available if guide unattended is enabled.

commitAmountAsync(amount)

Performs partial commit-operation after a successful Transaction call.

Returns immediately and calls commitCompleted on all notifiers once finished.

Parameters:
Name Type Description
amount timapi.Amount Amount to commit

commitAsync()

Performs Commit-operation after a successful Transaction call.

Returns immediately and calls commitCompleted on all notifiers once finished.

connectAsync()

Initiates a connection to the EFT Terminal. Calling connectAsync is not needed normally, because all methods make first a connect, if not connected.

Returns immediately and calls connectCompleted on all notifiers once finished.

counterRequestAsync(counterType)

Get counter information's from the EFT Terminal.

Returns immediately and calls counterRequestCompleted on all notifiers once finished.

Parameters:
Name Type Description
counterType timapi.constants.CounterType

dccRatesAsync()

Requests DCC rates from the EFT Terminal. The DCC rates are returned as receipt.

Returns immediately and calls dccRatesCompleted on all notifiers once finished.

deactivateAsync()

Closes a user shift. If the shift is already closed, no error is returned.

Returns immediately and calls deactivateCompleted on all notifiers once finished.

disconnectAsync()

Interrupts the connection to the EFT Terminal.

Returns immediately and calls disconnected on all notifiers once disconnect happened.

dispose()

Dispose of terminal.

ejectCardAsync()

Eject a card from the card reader.

Returns immediately and calls ejectCardCompleted on all notifiers once finished.

Note: This method is only available if guide unattended is enabled.

finishCheckoutAsync()

This function is used to finish a previously started checkout process with StartCheckout and to retrieve consumer loyalty data from the terminal that has been collected during this checkout process.

Returns immediately and calls finishCheckoutCompleted on all notifiers once finished.

Note: This method is only available if guide valueAddedServices is enabled.

getActSeqCounter() → {Number}

Get activation sequence counter
Returns:
activation sequence counter

Type: Number

getBrands() → {Array.<timapi.Brand>}

Get brands

Note: This data is available after a login or application information request has been performed.

Returns:
brands or empty list if not retreived yet

Type: Array.<timapi.Brand>

getConfigData() → {timapi.ConfigData}

Get configuration data

Note: This data is available after a system information request has been performed.

Returns:
configuration data or undefined if not retrieved yet

Type: timapi.ConfigData

getEcrData() → {Array.<timapi.EcrInfo>}

Get ecr Data
Returns:
ecrData

Type: Array.<timapi.EcrInfo>

getFeatures() → {timapi.Features}

Get features or undefined if not retrieved yet.
Returns:
Retreived terminal-features, or undefined if not retreived yet

Type: timapi.Features

getMerchantOptions() → {Array.<timapi.MerchantOption>}

Get merchant options
Returns:
Merchant options

Type: Array.<timapi.MerchantOption>

getPosId() → {String}

Get POS identifier
Returns:
POS identifier

Type: String

getPrintOptions() → {Array.<timapi.PrintOption>}

Get print options
Returns:
Print options

Type: Array.<timapi.PrintOption>

getSettings() → {timapi.TerminalSettings}

Get immutable copy of terminal settings
Returns:

Type: timapi.TerminalSettings

getTerminalId() → {String}

Get terminal identifier of connected terminal. Returns empty string if the terminal identifier is not known. The terminal identifier is available after logging in to the terminal
Returns:
Terminal identifier

Type: String

getTerminalStatus()

Get terminal status.

getTransactionData() → {timapi.TransactionData}

Get transaction data
Returns:
transaction data

Type: timapi.TransactionData

getUserId() → {String}

Get user identifier
Returns:
User identifier

Type: String

hardwareInformationAsync()

Get hardware information from the EFT Terminal.

Returns immediately and calls hardwareInformationCompleted on all notifiers once finished.

hasSwUpdate() → {Boolean}

Software update is available
Returns:
true if software update is available

Type: Boolean

holdCommit()

Extends the Commit timeout if the terminal needs additional time before the Commit shall be performed. An example could be on a public transport vending machine: if the machine is printing multiple tickets and this printing action would extend the commit timeout, a HoldCommit notification shall be sent to extend the Commit timeout as well. If the printing action fails after some tickets a partial commit can be performed.

Note: This method is only available if unattended is enabled.

initTransactionAsync(displayAmount, amount)

Initialize a transaction knowing the amount or the card type.

Returns immediately and calls initTransactionCompleted on all notifiers once finished.

Parameters:
Name Type Description
displayAmount Boolean
amount timapi.Amount

loginAsync()

Activate a communication session between the ECR and the terminal.

Returns immediately and calls loginCompleted on all notifiers once finished.

Note: Before calling set the print options, POS identifier and manufacturer flags set in the terminal instance.

Side-Effect: After completing the request updates the features, brands and terminal identifier in the terminal instance. Fetching these information can be disabled if Auto-FetchBrands is disabled in timapi.TerminalSettings.

logoutAsync()

Terminates an active communication session between the ECR and the terminal.

Returns immediately and calls logoutCompleted on all notifiers once finished

loyaltyDataAsync(functionType, dataType, data, retainCard)

This function is used to query and configure loyalty information.

Returns immediately and calls loyaltyDataCompleted on all notifiers once finished.

Note: This method is only available if guide valueAddedServices is enabled.

Parameters:
Name Type Description
functionType timapi.constants.LoyaltyFunctionType Defines what kind of loyalty mode will be used.
dataType String Specifies type of loyalty data. Mandatory for functionType init, update, deinit.
data uint8Array Loyalty data.
retainCard Boolean True to not eject card otherwise false.

openDialogModeAsync()

Open dialog mode on the terminal.

Returns immediately and calls openDialogModeCompleted on all notifiers once finished.

openMaintenanceWindowAsync()

Opens the maintenance window to the terminal so it can perform collected maintenance requests on its own, without interaction with the ECR. The terminal shall respond immediately to the ECR request whether it is able to handle the request or not.

If the terminal is able to handle the request, the ECR is free itself to perform maintenance as well or it can monitor the terminal by reading the TerminalStatus notifications.

It is possible that the connection between ECR and EFT terminal is terminated due to one or multiple reboot processes.

Returns immediately and calls openMaintenanceWindowCompleted on all notifiers once finished.

Note: This method is only available if guide unattended is enabled.

openReaderAsync()

Open the shutter of the card reader.

Returns immediately and calls openReaderCompleted on all notifiers once finished.

Note: This method is only available if guide unattended is enabled.

provideLoyaltyBasketAsync(basket)

This function is used to provide the terminal with a LoyaltyBasket if the corresponding loyalty scheme requires it.

Returns immediately and calls provideLoyaltyBasketCompleted on all notifiers once finished.

Note: This method is only available if guide valueAddedServices is enabled.

Parameters:
Name Type Description
basket Array.<timapi.LoyaltyItem> Basket as list of loyalty-items

rebootAsync()

Force the EFT Terminal to reboot

Returns immediately and calls rebootCompleted on all notifiers once finished.

receiptRequestAsync(type)

Receive the latest receipt or a list of silent receipts.

Returns immediately and calls receiptRequestCompleted on all notifiers once finished.

Parameters:
Name Type Description
type timapi.constants.ReceiptRequestType Type of receipts to receive.

reconciliationAsync()

Force the EFT Terminal to transmit all financial transactions to the host system.

Returns immediately and calls reconciliationCompleted on all notifiers once finished.

reconfigAsync()

Force the EFT Terminal to get the configuration from the service center.

Returns immediately and calls reconfigCompleted on all notifiers once finished.

removeListener()

Unregister listener.
Throws:
  • IllegalArgumentException If listener is undefined.
  • IllegalArgumentException If listener is not registered.

rollbackAsync()

Prevents a transaction from being committed to the transaction log and generates a technical reversal of the authorization.

For payment protocols supporting the function a declined receipt may be generated.

Returns immediately and calls rollbackCompleted on all notifiers once finished.

sendCardCommandAsync(requests)

This function is used for a direct communication with the inserted card using APDUs. It is possible to send a list of APDU command in the request (sixml:CommandRequestList) and to set responses that shall be accepted as "Positive" responses using sixml:PositiveAnswerList.

Each sixml:CommandRequest is numbered with a unique order number (starting with 1). In the response, the terminal sends the response of the device for each CommandRequest, including the order number of the request.

If the device answers with a negative response (i.e. SW1SW2 != 9000 or other as "positive" defined answers using sixml:PositiveAnswerList), the processing of the sixml:CommandRequests is aborted, and the remaining commands are not sent to the device.

Furthermore it can be defined which dialogs shall be shown using the container sixml:CommandResources in the following use cases:

  • Dialog shown as preparation before sending an APDU command: sixml:PreResource
  • Dialog shown during APDU command execution: sixml:ExecutionResource
  • Dialog shown after receiving a positive response: sixml:PositiveResource
  • Dialog shown after receiving a negative response: sixml:NegativeResource

Returns immediately and calls sendCardCommandCompleted on all notifiers once finished.

Note: This method is only available if guide dialog is enabled.

Parameters:
Name Type Description
requests Array.<timapi.CommandRequest>

setEcrData(ecrData)

Set ecr data
Parameters:
Name Type Description
ecrData Array.<timapi.EcrInfo> Array of ecr data

setMerchantOptions(merchantOptions)

Set merchant options
Parameters:
Name Type Description
merchantOptions Array.<timapi.MerchantOption> Merchant options

setPosId(posId)

Set POS identifier
Parameters:
Name Type Description
posId String POS identifier

setPrintOptions(printOptions)

Set print options
Parameters:
Name Type Description
printOptions Array.<timapi.PrintOption> Print options

setTransactionData(ecrData)

Set transaction data
Parameters:
Name Type Description
ecrData timapi.TransactionData Array of ecr data

setUserId(userId)

Set user identifier
Parameters:
Name Type Description
userId String User identifier

showDialogAsync(request)

Show dialog on the terminal.

Returns immediately and calls showDialogCompleted on all notifiers once finished.

Note: This method is only available if guide dialog is enabled.

Parameters:
Name Type Description
request timapi.ShowDialogRequest Show dialog request

showSignatureCaptureAsync(request)

Show signature capture on the terminal.

Can be called only if dialog mode is open.

Returns immediately and calls showSignatureCaptureCompleted on all notifiers once finished.

Note: This method is only available if guide dialog is enabled.

Parameters:
Name Type Description
request ShowSignatureCaptureRequest Show signature capture request

softwareUpdateAsync()

Force the EFT Terminal to start a Software Update.

Returns immediately and calls softwareUpdateCompleted on all notifiers once finished.

startCheckoutAsync()

This function is used to start a Checkout process at the POS to collect card and/or cardholder loyalty information before a transaction is started. Therefore the SIX QR code is displayed at the terminal. The timeout how long the QR code shall be displayed on the terminal before returning to its Idle screen can be defined in the Login request using the OptionType - QRCTimeout.

Returns immediately and calls startCheckoutCompleted on all notifiers once finished.

Note: This method is only available if guide valueAddedServices is enabled.

systemInformationAsync()

Request system information from the EFT Terminal.

Note: Set EcrData property before calling SystemInformation.

Returns immediately and calls systemInformationCompleted on all notifiers once finished.

transactionAsync(type, amount)

Starts an EFT Terminal Transaction.

Returns immediately and calls transactionCompleted on all notifiers once finished.

Note: The transaction parameters are taken from TransactionData terminal property since those do not change often if at all (default parameters).

Parameters:
Name Type Description
type timapi.constants.TransactionType Financial Transaction Function.
amount timapi.Amount Transaction amount.

transactionCashbackAsync(type, amount, amountCashback)

Starts an EFT Terminal Transaction with Cashback amount.

Returns immediately and calls transactionCompleted on all notifiers once finished.

Note: The transaction parameters are taken from TransactionRequest terminal property since those do not change often if at all (default parameters).

Note: This method is only available if guide advanced_retail is enabled.

Parameters:
Name Type Description
type timapi.constants.TransactionType Financial Transaction Function.
amount timapi.Amount Transaction amount.
amountCashback timapi.Amount Cashback amount.

transactionTipAsync(type, amount, amountTip)

Starts an EFT Terminal Transaction with Tip amount.

Returns immediately and calls transactionCompleted on all notifiers once finished.

Note: The transaction parameters are taken from TransactionRequest terminal property since those do not change often if at all (default parameters).

Note: This method is only available if guide gastro is enabled.

Parameters:
Name Type Description
type timapi.constants.TransactionType Financial Transaction Function.
amount timapi.Amount Transaction amount.
amountTip timapi.Amount Proposed tip amount.

transactionWithRequestAsync(type, request)

Starts an EFT Terminal Transaction with a manually built request.

Returns immediately and calls transactionCompleted on all notifiers once finished.

Note: Allows enhanced transaction configuration compared to transactionAsync

Parameters:
Name Type Description
type timapi.constants.TransactionType Financial Transaction Function.
request timapi.TransactionRequest Transaction parameters as TransactionRequest object.