Overview
Methods-Overview
- activateAsync()
- activateServiceMenuAsync()
- addEcrData(ecrInfo)
- addListener()
- amtAdjustment(amount)
- amtAdjustmentVas(amount, amountDiscount, loyaltyCouponList, loyaltyInformationList)
- applicationInformationAsync()
- balanceAsync()
- balanceInquiryAsync()
- cancel()
- cancelUnattended(silent, retainCard)
- canDcc() → {Boolean}
- canDeclinedReceipts() → {Boolean}
- canMultiAccountSelection() → {Boolean}
- changeSettingsAsync(settings)
- closeDialogModeAsync()
- closeMaintenanceWindowAsync()
- closeReaderAsync()
- commitAmountAsync(amount)
- commitAsync()
- connectAsync()
- counterRequestAsync(counterType)
- dccRatesAsync()
- deactivateAsync()
- disconnectAsync()
- dispose()
- ejectCardAsync()
- finishCheckoutAsync()
- getActSeqCounter() → {Number}
- getBrands() → {Array.<timapi.Brand>}
- getConfigData() → {timapi.ConfigData}
- getEcrData() → {Array.<timapi.EcrInfo>}
- getFeatures() → {timapi.Features}
- getMerchantOptions() → {Array.<timapi.MerchantOption>}
- getPosId() → {String}
- getPrintOptions() → {Array.<timapi.PrintOption>}
- getSettings() → {timapi.TerminalSettings}
- getTerminalId() → {String}
- getTerminalStatus()
- getTransactionData() → {timapi.TransactionData}
- getUserId() → {String}
- hardwareInformationAsync()
- hasSwUpdate() → {Boolean}
- holdCommit()
- initTransactionAsync(displayAmount, amount, functionHint)
- loginAsync()
- logoutAsync()
- loyaltyDataAsync(functionType, dataType, data, retainCard)
- openDialogModeAsync()
- openMaintenanceWindowAsync()
- openReaderAsync()
- printOnTerminalAsync(ticketData)
- provideLoyaltyBasketAsync(basket)
- provideVasResultAsync(basket)
- rebootAsync()
- receiptRequestAsync(type)
- reconciliationAsync(reconciliationMode)
- reconfigAsync()
- removeListener()
- rollbackAsync()
- sendCardCommandAsync(requests)
- setCompactReceiptFormatter()
- setCustomReceiptFormatter(customReceiptFormatter)
- setEcrData(ecrData)
- setMerchantOptions(merchantOptions)
- setNormalReceiptFormatter()
- setPosId(posId)
- setPrintOptions(printOptions)
- setReceiptFormatter(formatter)
- setSuperCompactReceiptFormatter()
- setTransactionData(ecrData)
- setUltraCompactReceiptFormatter()
- setUserId(userId)
- showDialogAsync(request)
- showSignatureCaptureAsync(request)
- softwareUpdateAsync()
- startCheckoutAsync()
- systemInformationAsync()
- transactionAsync(type, amount)
- transactionCashbackAsync(type, amount, amountCashback)
- transactionTipAsync(type, amount, amountTip)
- transactionWithRequestAsync(type, request)
Constructor
new Terminal(settings)
Parameters:
Name | Type | Description |
---|---|---|
settings |
timapi.TerminalSettings |
Methods
activateAsync()
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)
To remove all elements use setEcrData instead.
Parameters:
Name | Type | Description |
---|---|---|
ecrInfo |
timapi.EcrInfo | ecr information to add |
addListener()
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)
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()
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:
Type: Boolean
canDeclinedReceipts() → {Boolean}
Returns:
Type: Boolean
canMultiAccountSelection() → {Boolean}
Returns:
Type: Boolean
changeSettingsAsync(settings)
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)
Returns immediately and calls commitCompleted on all notifiers once finished.
Parameters:
Name | Type | Description |
---|---|---|
amount |
timapi.Amount | Amount to commit |
commitAsync()
Returns immediately and calls commitCompleted on all notifiers once finished.
connectAsync()
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)
Returns immediately and calls counterRequestCompleted on all notifiers once finished.
Parameters:
Name | Type | Description |
---|---|---|
counterType |
timapi.constants.CounterType |
dccRatesAsync()
Returns immediately and calls dccRatesCompleted on all notifiers once finished.
deactivateAsync()
Returns immediately and calls deactivateCompleted on all notifiers once finished.
disconnectAsync()
Returns immediately and calls disconnected on all notifiers once disconnect happened.
dispose()
ejectCardAsync()
Returns immediately and calls ejectCardCompleted on all notifiers once finished.
Note: This method is only available if guide unattended is enabled.
finishCheckoutAsync()
Returns immediately and calls finishCheckoutCompleted on all notifiers once finished.
Note: This method is only available if guide valueAddedServices is enabled.
getActSeqCounter() → {Number}
Returns:
Type: Number
getBrands() → {Array.<timapi.Brand>}
Note: This data is available after a login or application information request has been performed.
Returns:
Type: Array.<timapi.Brand>
getConfigData() → {timapi.ConfigData}
Note: This data is available after a system information request has been performed.
Returns:
Type: timapi.ConfigData
getFeatures() → {timapi.Features}
Returns:
Type: timapi.Features
getMerchantOptions() → {Array.<timapi.MerchantOption>}
Returns:
Type: Array.<timapi.MerchantOption>
getPosId() → {String}
Returns:
Type: String
getPrintOptions() → {Array.<timapi.PrintOption>}
Returns:
Type: Array.<timapi.PrintOption>
getSettings() → {timapi.TerminalSettings}
Returns:
Type: timapi.TerminalSettings
getTerminalId() → {String}
Returns:
Type: String
getTerminalStatus()
getTransactionData() → {timapi.TransactionData}
Returns:
Type: timapi.TransactionData
getUserId() → {String}
Returns:
Type: String
hardwareInformationAsync()
Returns immediately and calls hardwareInformationCompleted on all notifiers once finished.
hasSwUpdate() → {Boolean}
Returns:
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, functionHint)
Returns immediately and calls initTransactionCompleted on all notifiers once finished.
Parameters:
Name | Type | Description |
---|---|---|
displayAmount |
Boolean | |
amount |
timapi.Amount | |
functionHint |
timapi.constants.FunctionHint |
loginAsync()
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()
Returns immediately and calls logoutCompleted on all notifiers once finished
loyaltyDataAsync(functionType, dataType, data, retainCard)
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()
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()
Returns immediately and calls openReaderCompleted on all notifiers once finished.
Note: This method is only available if guide unattended is enabled.
printOnTerminalAsync(ticketData)
The PrintOnTerminal-function is used to send a freetext preformatted ticket from ECR to terminal. The ticket is then printed on the terminal printer. The ticket must be formatted according [B39].
Note: This method is only available if guide dialog is enabled.
Parameters:
Name | Type | Description |
---|---|---|
ticketData |
String | Content to print. |
provideLoyaltyBasketAsync(basket)
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 |
provideVasResultAsync(basket)
Returns immediately and calls provideVasResultCompleted on all notifiers once finished.
Note: This method is only available if guide valueAddedServices is enabled.
Parameters:
Name | Type | Description |
---|---|---|
basket |
timapi.VasResult | Vas result to send. |
rebootAsync()
Returns immediately and calls rebootCompleted on all notifiers once finished.
receiptRequestAsync(type)
Returns immediately and calls receiptRequestCompleted on all notifiers once finished.
Parameters:
Name | Type | Description |
---|---|---|
type |
timapi.constants.ReceiptRequestType | Type of receipts to receive. |
reconciliationAsync(reconciliationMode)
Returns immediately and calls reconciliationCompleted on all notifiers once finished.
Parameters:
Name | Type | Description |
---|---|---|
reconciliationMode |
timapi.constants.ReconciliationMode | Optional reconciliation mode |
reconfigAsync()
Returns immediately and calls reconfigCompleted on all notifiers once finished.
removeListener()
Throws:
-
IllegalArgumentException If listener is undefined.
-
IllegalArgumentException If listener is not registered.
rollbackAsync()
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> |
setCompactReceiptFormatter()
setCustomReceiptFormatter(customReceiptFormatter)
Parameters:
Name | Type | Description |
---|---|---|
customReceiptFormatter |
timapi.CustomReceiptFormatter | Custom receipt format definition. |
setEcrData(ecrData)
Parameters:
Name | Type | Description |
---|---|---|
ecrData |
Array.<timapi.EcrInfo> | Array of ecr data |
setMerchantOptions(merchantOptions)
Parameters:
Name | Type | Description |
---|---|---|
merchantOptions |
Array.<timapi.MerchantOption> | Merchant options |
setNormalReceiptFormatter()
setPosId(posId)
Parameters:
Name | Type | Description |
---|---|---|
posId |
String | POS identifier |
setPrintOptions(printOptions)
Parameters:
Name | Type | Description |
---|---|---|
printOptions |
Array.<timapi.PrintOption> | Print options |
setReceiptFormatter(formatter)
Parameters:
Name | Type | Description |
---|---|---|
formatter |
timapi.DefaultReceiptFormatter | Receipt format. |
setSuperCompactReceiptFormatter()
setTransactionData(ecrData)
Parameters:
Name | Type | Description |
---|---|---|
ecrData |
timapi.TransactionData | Array of ecr data |
setUltraCompactReceiptFormatter()
setUserId(userId)
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()
Returns immediately and calls softwareUpdateCompleted on all notifiers once finished.
startCheckoutAsync()
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)
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)
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. |