Tender Retail

10 Tender Retail

This document covers EFTLink Integration with Tender Retail Payment Systems. It should be read in conjunction with the Oracle Retail EFTLink Framework Installation and Configuration Guide.

EFTLink General

This document assumes static EFTLink configuration. When deploying with a POS that supports dynamic configuration, all property settings referred to below should be set on the POS, and not directly into local property files.

Minimum Version

The Tender Retail interface requires a minimum EFTLink version of 20.0.

System Architecture

EFTLink connects to the Tender Retail application that is installed on the same PC as the POS, using a proprietary socket protocol. The Tender Retail application must be started.

Note:

This document does not cover the install of the Tender Retail software.

Fileset

In addition to standard EFTLink files, Tender Retail uses:

cores/tenderretail/epstenderretail.jar
tenderretail.properties
Lang<CC>_<Core>.properties – Language translation file, for further information see Language.
data/tenderretail.keystore - keystore file is used to encrypt Givex user id and password within the tenderretail.properties. This file needs to be generated at installation but only if using Givex as the gift card provider. Please see the next section for details.

Keystore

The encryption key must be generated and stored in a keystore. To achieve this, the following steps must be followed:

Open a terminal window and change directory to where the script file resides.

For Windows: Type encrypt-tenderretail.bat –k [<keystore name> <properties file>].

For example, encrypt-tenderretail.bat –k

For Linux: Type encrypt-tenderretail.sh –k [<keystore name> <properties file>].

For Example, ./sudo encrypt-tenderretail.sh –k

Keystore file will be generated and stored in the data directory. If the keystore name and the properties file names are not specified, then the default values (tenderretail.keystore, tenderretail.properties) will be used.

Encryption

If using Givex for the SVC payment then the following settings within the tenderretail.properties file need to be encrypted:

user.id
user.pin

To achieve this, the following steps must be followed:

To encrypt a value: Open a terminal window and change directory to where the script file resides.

For Windows: Type encrypt-tenderretail.bat –e <keystore name> <properties file> <value>.

For example, encrypt-tenderretail.bat –e

*For Linux: Type encrypt—tenderretail.sh –e [<keystore name> <properties file> <value>].

For example, sudo ./ encrypt-tenderretail.sh –e

The user will be presented with prompts to provide the value(s) which are to be encrypted. Once entered the corresponding properties keys will be automatically updated with the encrypted values.

Note:

If the keystore name, properties file and unencrypted text is included as arguments then the encrypted value and initialization vector will be outputted to the console which must be copied and pasted to relevant property key within tenderretail.properties. This process then needs to be repeated for every value that is required to be encrypted.

To re-encrypt; Open a terminal window and change directory to where the script file resides.

For Windows: Type encrypt-tenderretail.bat –r [<keystore name> <properties file> <keygen type> <cipher type> <key size> <iterations>].

For example, encrypt-tenderretail.bat –r

*For Linux: Type encrypt-tenderretail.sh –r [<keystore name> <properties file> <keygen type> <cipher type> <key size> <iterations>].

For example, sudo ./ encrypt-tenderretail.sh -r

The key values to be re-encrypted will be taken from the properties file, re-encrypted and the properties file will be automatically updated.

* You may be required to give script file(s) execution rights for example, chmod +x <PathToFile>

Note:

When using AES algorithm with a keysize that is greater than 128, you may get java.security.InvalidKeyException: Illegal key size or default parameters. If so, Additional Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files will need to be downloaded and extracted to %JAVA_HOME%/jre/lib/security/.

PED Initialization

It is possible to send a Ped Initialization request to the tender retail application via the command line using arguments without EFTLink running.

To achieve this, EFTLink must not be running, and the tender retail application must be running and accepting requests.

Note:

A windows batch file is provided called initializePed.bat, which requires to be run from the root folder of eftlink. If the batch file is run without supplying any arguments it will attempt to gather the mandatory and secondary arguments from the tenderretail.properties file.

Table 10-1 Mandatory Arguments

Argument	Description	Example
-i	Instructs EFTLink to make a ped initialization request. If the terminal id or any of the secondary arguments are not provided then the core will attempt to get them from the tenderretail.properties file.	`java manito.eft.tenderretail.Main -i`
terminalId	Sets terminal.id.	`java manito.eft.tenderretail.Main -i 300`

Table 10-2 Secondary Arguments

Argument	Description	Example
hostName	Sets mcm.host.name.	`java manito.eft.tenderretail.Main -i 300 localhost`
hostPort	Sets mcm.host.port.	j`ava manito.eft.tenderretail.Main -i 300 localhost 3858`
timeout_1	Sets connection.timeout.1.	j`ava manito.eft.tenderretail.Main -i 300 localhost 3858 120000`
timeout_2	Sets connection.timeout.2.	`java manito.eft.tenderretail.Main -i 300 localhost 3858 120000 2000`
ackInterval	Sets do.positive.ack.	`java manito.eft.tenderretail.Main -i 300 localhost 3858 120000 2000 5000`
checkServerOnStartup	Sets check.mcm.server.on.startup.	`java manito.eft.tenderretail.Main -i 300 localhost 3858 120000 2000 5000 true`

Language

The translation files for this core should not require alteration, but if necessary then this can be accomplished by amending the relevant Lang<CC>_<Core>.properties within the base eftlink folder.

The language used will follow the language set in the EFTLink framework; see the Oracle Retail EFTLink Framework Installation and Configuration Guide, EFTLink General Information, Translation section.

EftlinkConfig.properties

DisplayLanguage = EN

Supported country codes are CN, DE, EN, ES, FR, IT, JP, NL, PT, RU and SV.

Core Classname

The following should have been set in the EftlinkConfig.properties file by installcore.bat or installcore.sh

EPSCore0=manito.eft.tenderretail.TenderRetailCore

Configuration Settings

The full set of configuration properties is defined and commented in tenderretail.properties.

Key Settings

Settings that may be different for all POS.

Table 10-3 Tender Retail - Key Settings

Setting Description Default Example

Setting	Description	Default	Example
terminal.id	The bank supplied ID number specific to the station processing the transaction as configured in the Tender Retail Merchant Connect Multi Credit/Debit server. Only one terminal is supported.	None	`terminal.id = 300`
wallet.terminal.id	The e-wallet supplied ID number specific to the station processing the transaction as configured in the Tender Retail Merchant Connect Multi.	None	wallet.terminal.id = 007
wallet.host	Which wallet host to use. Values are Citcon or Alipay. Important! This setting must match the configuration of Tender Retail's application. Misalignment of the configuration could cause erroneous transaction results.	Citcon	wallet.host = Alipay

terminal.id

The bank supplied ID number specific to the station processing the transaction as configured in the Tender Retail Merchant Connect Multi Credit/Debit server. Only one terminal is supported.

None

terminal.id = 300

wallet.terminal.id

The e-wallet supplied ID number specific to the station processing the transaction as configured in the Tender Retail Merchant Connect Multi.

None

wallet.terminal.id = 007

wallet.host

Which wallet host to use. Values are Citcon or Alipay.

Important! This setting must match the configuration of Tender Retail's application.

Misalignment of the configuration could cause erroneous transaction results.

Citcon

wallet.host = Alipay

Secondary Settings

These settings are normally correct at their default values but can be overridden if necessary.

Table 10-4 Tender Retail - Secondary Settings

Setting	Description	Default	Example
mcm.host.folder	The path to the folder where the Tender Retail's application is installed.	\MerchantConnectMulti	`mcm.host.folder = C:\MerchantConnectMulti`
mcm.host.port	The socket port for making payment requests.	3858	`mcm.host.port = 3858`
mcm.host.name	The file location of where Tender Retail's application is installed.	localhost	`mcm.host.name = localhost`
check.mcm.server.on.startup	Defines whether Tender Retail's application should be contacted initially when starting the EFT adapter.	true	`check.mcm.server.on.startup = true`
communications.type	Sets the communications type.	ip	`communications.type = ip`
connection.timeout.1	This parameter configures the time until when the Tender Retail application is expected to respond to a request. This includes the time needed to swipe the card at the PIN Pad terminal (if required) and to contact the financial institution.	120000	`connection.timeout.1 = 120000`
connection.timeout.2	This parameter determines the interval in which Tender Retail's application is expected to continue delivering data once it began to deliver something.	2000	`connection.timeout.2 = 2000`
timeout.saf	This parameter determines the time Tender Retail's application must empty its store and forward queue. Note: If there is a communication problem with the eft transaction processor or there are lots of transactions in the queue it may take quite a while to process the queue.	600000	`timeout.saf`
do.positive.ack	Determines whether the responses are acknowledged. The value specifies the interval in which Tender Retail's application expects the acknowledgements.	5000	`do.positive.ack = 5000`
currency.code	Used in conjunction with SVS Gift card to set the currency code.	840	`currency.code = 840`
currency.symbol	Line display currency symbol.	$	`currency.symbol = $`
Use.tokens	Determines whether Tender Retail's application is set to use tokens. This setting must match the configuration of Tender Retail's application.	true	`use.tokens = true`
combine.receipts	Turn on/off POS combine receipt.	false	`combine.receipts = false`
combine.receipts.suppress.lines	When combine.receipt is true, sets which line number to suppress.	NA	`combine.receipts.suppress.lines=1,3,5`
combine.receipts.suppress.strings	When combine.receipt is true, sets which line to suppress when strings are matched.	NA	`combine.receipts.suppress.strings = Date,Time`
exclude.combine.receipts.Strings	Sets what line to suppress when strings are matched.	NA	`exclude.combine.receipts.Strings = signature,welcome,ball`
Void.header.n [where n is >0]	Specify several header lines to include on void receipts (maximum of 3 supported lines).	None	`void.header.1 = ********` `void.header.2 = VOID ` `void.header.3 = ********`
Void.footer.n [where n is >0]	Specify several footer lines to include on void receipts.	None	`void.footer.1 = ********` `void.footer.2 = VOID ` `void.footer.3 = ********`
electronic.signature	Enable the extracting of electronic signature from the device for display/approval on the POS.	false	`Electronic.signature=true`
electronic.signature.timeout	Sets the time out for “Amount of time to wait after a user completes signing”.	25	`electronic.signature.timeout = 60`
Socket.file.encoding	Overrides what character set to be used while reading the response on the socket from the Tender Retail client. The default character set on a windows jvm is cp1252, if any other charset is specified by the jvm (-Dfile.encoding) the socket.file.encoding below will automatically be set to ISO-8859-1. Setting the character set below will override any defaults.		`socket.file.encoding=cp1252`
perform.card.range.lookup	If true, EFTLink will use its mapping file CardRange.xml to determine the card scheme name.	false	`perform.card.range.lookup=false`
suppress.additional.message.prompt	If true, suppresses the message prompt on a failed transaction.	false	`suppress.additional.message.prompt = false`
exclude.additional.message.prompt.by.response.code	Comma delimited exception list if suppress.additional.message.prompt is true.		`exclude.additional.message.prompt.by.response.code =`
suppress.additional.message.prompt.for.gift.card	If true, suppresses the message prompt on a failed gift card transaction.	false	`suppress.additional.message.prompt.for.gift.card = false`
exclude.additional.message.prompt.for.gift.card.by.response.code	Comma delimited exception list if suppress.additional.message.prompt.for.gift.card is true.		`exclude.additional.message.prompt.for.gift.card.by.response.code =`
add.response.properties.to.misc.data	Specify tender retail response property codes (comma delimited) to be sent through miscellaneous data within the card service response.	SEQ,ISO,FBK,DSP	`add.response.properties.to.misc.data = SEQ,ISO,FBK,DSP`
manual.auth.input.type.alphanumeric	Sets the input validation to alphanumeric for entering the authorization code.	false	`manual.auth.input.type.alphanumeric = false`
manual.auth.minimum.length	Sets the minimum length for an authorization code.	6	`manual.auth.minimum.length = 6`
manual.auth.maximum.length	Sets the maximum length for an authorization code.	6	`manual.auth.maximum.length = 6`
manual.auth.retrys	Sets the number of retry attempts for entering an authorization code.	3	`manual.auth.retrys = 3`
swipe.fallback	Turns on/off the ability to prompt for manual keyed entry.	false	`swipe.fallback = false`
svc.card.type	Sets the gift card provider. Valid values are SVS or Givex.	svs	`svc.card.type = svs`
svs.pin.entry	Turn on/off the prompting for pin for SVS Gift Cards.	false	`svs.pin.entry = false`
svs.pin.entry.on.ped	Turn on/off the prompting for pin capture on the ped. if false the pin capture is done on the POS.	false	`svs.pin.entry.on.ped = false`
svs.pin.entry.types	Determines which tender types require pin capture.	83,A3,D3	`svs.pin.entry.types = 83,A3,D3`
svs.pin.minimum.length	Sets the minimum length for a pin.	4	`svs.pin.minimum.length = 4`
svs.pin.maximum.length	Sets the maximum length for a pin.	4	`svs.pin.maximum.length = 4`
svs.pin.retrys	Sets the number of retry attempts	3	`svs.pin.retrys = 3`
givex.user.id	User id provided by Givex.		`givex.user.id = [encrypted user id string`]
givex.user.id.iv	Encrypted password initialization vector.		`givex.user.id.iv = [encrypted user id iv string]`
givex.password	Password provided by Givex.		`givex.password = [encrypted password string]`
givex.password.iv	Encrypted password initialization vector.		`givex.password.iv = [encrypted password iv string]`
givex.allow.partial.tender	Specify whether to allow partial tendering of gift cards.	true	`givex.allow.partial.tender = true`
givex.pin.entry	Turn on/off the prompting for security pin for Givex Cards.	false	`givex.pin.entry= false`
givex.pin.entry.types	Sets which tender types require security pin capture.	73,83	`givex.pin.entry.types = 73,83`
givex.pin.minimum.length	Sets the minimum required length for a Givex security pin.	6	`givex.pin.minimum.length = 6`
givex.pin.maximum.length	Sets the maximum required length for a Givex security pin.	6	`givex.pin.maximum.length = 6`
givex.pin.retrys	Sets the maximum number of retries allowed.	3	`givex.pin.retrys = 3`
crypto.keygenType	Sets keygen algorithm type.	AES	`crypto.keygenType = AES`
crypto.cipherType	Sets cipher algorithm type.	AES/CBC/PKCS5Padding	`crypto.cipherType = AES/CBC/PKCS5Padding`
crypto.keySize	Sets size of the key store.	128	`crypto.keySize = 128`
crypto.iterations	Sets number of iterations.	100000	`crypto.iterations = 100000`
crypto.factoryinstance	Sets crypto factory instance for keystore password encryption.	PBKDF2WithHmacSHA512	`crypto.factoryinstance = PBKDF2WithHmacSHA512`
crypto.secretkeyspec	Sets crypto secret key spec for keystore password encryption.	AES	`crypto.secretkeyspec = AES`
crypto.keystoretype	Sets keystore type.	JKS	crypto.keystoretype = JKS
crypto.digest	Sets digest for keystore password.	SHA-512	`crypto.digest = SHA-512`
crypto.hashbyteSize	Sets hash byte size for keystore password.	384	`crypto.hashbyteSize = 384`
AdminMenu0.X	Specifies the ability to customize the Admin Menu. Replace X with a value between 0 - 4.	AdminMenu0.1 = TXT_DAY_END, Day End AdminMenu0.2 = TXT_PINPAD_INITIALIZATION, PINPad Initialization AdminMenu0.3 = TXT_SIGNATURE_CAPTURE, Signature Capture AdminMenu0.4 = TXT_CANCEL, Cancel	`AdminMenu0.1 = TXT_DAY_END, Day End` `AdminMenu0.2 = TXT_CANCEL, Cance`l
line.display.enabled	Enables line item display on PED.	false	`line.display.enabled = true`

Administration Functions

The terminal has some administration/maintenance functions. These can only be invoked from a dedicated EFT Maintenance menu button.

EFTLink uses DeviceProxy messages to display input prompts on the POS to manage these functions.

Table 10-5 Tender Retail - Administration Functions

Function	Description
Day End	Print a day report and close the current day. Manual alternative to automated reconciliation with closure.
PINPad Initialization	Sends a PINPad Initialization request.
Signature Capture	Sends request to test the signature capture functionality on the device.

Supported Functions

Below is a list of supported functionalities of the interface to Tender Retail.

Table 10-6 Tender Retail - Supported Functions

Function		Description
Sale State Notifications		Sends line items through to the device so the customer display can be updated in line with the POS.
Payment		Sends payment request to Tender Retail's application. The client will return a response message with formatted receipt strings for customer and/or merchant receipts. In an event of referral or communication failure where authorization cannot be obtained online then a prompt for authorization code will appear; authorization code must be obtained via telephone. Appropriate receipts will be printed at the end of transaction.
Reversal		Sends reversal requests to Tender Retail's application. The client will reverse a transaction specified by the transaction number, found on the receipt, which must be captured by the POS and passed on to EFTLink.
Refund		Sends refund requests to Tender Retail's application. The client will refund a transaction with specified amount.
Tokenized Refund		Sends refund requests to Tender Retail's application. The client software will refund a transaction with specified token id.
SVC Redeem		Sends a gift or merchandise credit card payment request to the terminal. If there are not enough funds available, only the funds available will be deducted. The POS client will have to settle the transaction with another tender in this scenario.
SVC Redeem Reversal		Sends a gift or merchandise credit card payment reversal request to the terminal.
SVC Activate		Sends a gift or merchandise credit card Issuance request to Tender Retail's MCM software.EFTLink by default for SVS Gift card sends an Issuance message for RequestType=CardActivate. To process an activate message it will be necessary to send through via a card service request a MiscellaneousData element GiftCardType=Activate.For example, `<?xml version="1.0" encoding="UTF-8"?>` `<CardServiceRequest RequestType="CardActivate" ApplicationSender="POSSIM" WorkstationID="1" RequestID="1" RequestSubType="PresetValue">` `<POSdata LanguageCode="en">` `<POSTimeStamp>2019-05-13T16:50:03</POSTimeStamp>` `<TransactionNumber>479</TransactionNumber>` `<TransactionDay>2019-05-13</TransactionDay>` `</POSdata>` `<TotalAmount Currency="GBP">50.00</TotalAmount>` `<SaleItem ItemID="_1">` `<ProductCode>25</ProductCode>` `<Amount>50.00</Amount>` `<UnitMeasure>EA</UnitMeasure>` `<UnitPrice>50.00</UnitPrice>` `<Quantity>1</Quantity>` `<TaxCode>A</TaxCode>` `<TaxRate>0.00</TaxRate>` `<AdditionalProductCode>12345678</AdditionalProductCode>` `<AdditionalProductInfo>SVC Card</AdditionalProductInfo>` `</SaleItem>` `<MiscellaneousData>GiftCardType=Activate</MiscellaneousData>` `</CardServiceRequest>`
SVC Activate Reversal		Sends a gift or merchandise credit card activation request to Tender Retail's MCM software.
SVC Add Value		Sends a gift or merchandise credit card add value request to Tender Retail's MCM software. The card must be first activated before using this function.
SVC Add Reversal		Sends a gift or merchandise credit card payment request to Tender Retail's MCM software. Optionally a void will be activated in the core to avoid presenting the card for the reversal.
SVC Balance Enquiry		Sends a gift or merchandise credit card balance enquiry request to Tender Retail's MCM software.
SVC Unload (Cash Out)		Sends a gift or merchandise credit card cash out request to the Tender Retail's MCM software. All funds are deducted from the account and the cash back amount is returned to the POS. The account is not deactivated as part of this process.
Read Non-PCI Card		EFTLink sends a card swipe request to receive data for non-pci cards. The full pan is returned in clear text, unencrypted and without tokenization. PCI cards will return a blank PAN. As EFTLink doesn't currently have a direct mapping for requesting for a Token. As a work around to request for a token then send RequestType=CardSwipe within the CardServiceRequest. Include the string "GetToken" within the Card Value element and map the Card Type to either of the following value (taken from the tender retail technical specification document) 1 - Master Card 2 - Visa 3 - American Express 4 - Discover 6 - Enroute/Diners 7 - JCB < - Debit 0 - Unknown For example, `<?xml version="1.0" encoding="UTF-8"?>` `<CardServiceRequest RequestType="CardSwipe" ApplicationSender="MICROS" WorkstationID="1" RequestID="1">` `<POSdata LanguageCode="en">` `<POSTimeStamp>2019-05-10T16:30:20</POSTimeStamp>` `</POSdata>` `<CardValue CardType="0">` `<Token>GetToken</Token>` `</CardValue>` `</CardServiceRequest>`
Ewallet (Flow 3) Citcon / Alipay	Payment	Sends payment request to Tender Retail's application. The client will return a response message with formatted receipt strings for customer and/or merchant receipts. Appropriate receipts will be printed at the end of transaction.
	Refund	Sends refund requests to Tender Retail's application. The client will refund a transaction with specified amount.
	Cancel	Sends void/correction request for Payments or Refunds. Please note this is only supported for MCM direct to Alipay. MCM to Citon to Alipay is not supported.