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.

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.

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.

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.

commitAsync()

Performs Commit-operation after a successful Transaction call.

Returns immediately and calls commitCompleted on all notifiers once finished.

commitPartialAsync(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

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.

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

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

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.

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

softwareUpdateAsync()

Force the EFT Terminal to start a Software Update.

Returns immediately and calls softwareUpdateCompleted on all notifiers once finished.

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.