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.
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 thetenderretail.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. |
|
terminalId |
Sets terminal.id. |
|
Table 10-2 Secondary Arguments
Argument | Description | Example |
---|---|---|
hostName |
Sets mcm.host.name. |
|
hostPort |
Sets mcm.host.port. |
j |
timeout_1 |
Sets connection.timeout.1. |
j |
timeout_2 |
Sets connection.timeout.2. |
|
ackInterval |
Sets do.positive.ack. |
|
checkServerOnStartup |
Sets check.mcm.server.on.startup. |
|
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 |
---|---|---|---|
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 |
|
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.port |
The socket port for making payment requests. |
3858 |
|
mcm.host.name |
The file location of where Tender Retail's application is installed. |
localhost |
|
check.mcm.server.on.startup |
Defines whether Tender Retail's application should be contacted initially when starting the EFT adapter. |
true |
|
communications.type |
Sets the 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.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 |
|
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 |
|
do.positive.ack |
Determines whether the responses are acknowledged. The value specifies the interval in which Tender Retail's application expects the acknowledgements. |
5000 |
|
currency.code |
Used in conjunction with SVS Gift card to set the currency code. |
840 |
|
currency.symbol |
Line display 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 |
|
combine.receipts |
Turn on/off POS combine receipt. |
false |
|
combine.receipts.suppress.lines |
When combine.receipt is true, sets which line number to suppress. |
NA |
|
combine.receipts.suppress.strings |
When combine.receipt is true, sets which line to suppress when strings are matched. |
NA |
|
exclude.combine.receipts.Strings |
Sets what line to suppress when strings are matched. |
NA |
|
Void.header.n [where n is >0] |
Specify several header lines to include on void receipts (maximum of 3 supported lines). |
None |
|
Void.footer.n [where n is >0] |
Specify several footer lines to include on void receipts. |
None |
|
electronic.signature |
Enable the extracting of electronic signature from the device for display/approval on the POS. |
false |
|
electronic.signature.timeout |
Sets the time out for “Amount of time to wait after a user completes signing”. |
25 |
|
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. |
|
|
perform.card.range.lookup |
If true, EFTLink will use its mapping file CardRange.xml to determine the card scheme name. |
false |
|
suppress.additional.message.prompt |
If true, suppresses the message prompt on a failed transaction. |
false |
|
exclude.additional.message.prompt.by.response.code |
Comma delimited exception list if suppress.additional.message.prompt is true. |
|
|
suppress.additional.message.prompt.for.gift.card |
If true, suppresses the message prompt on a failed gift card transaction. |
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. |
|
|
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 |
|
manual.auth.input.type.alphanumeric |
Sets the input validation to alphanumeric for entering the authorization code. |
false |
|
manual.auth.minimum.length |
Sets the minimum length for an authorization code. |
6 |
|
manual.auth.maximum.length |
Sets the maximum length for an authorization code. |
6 |
|
manual.auth.retrys |
Sets the number of retry attempts for entering an authorization code. |
3 |
|
swipe.fallback |
Turns on/off the ability to prompt for manual keyed entry. |
false |
|
svc.card.type |
Sets the gift card provider. Valid values are SVS or Givex. |
svs |
|
svs.pin.entry |
Turn on/off the prompting for pin for SVS Gift Cards. |
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.types |
Determines which tender types require pin capture. |
83,A3,D3 |
|
svs.pin.minimum.length |
Sets the minimum length for a pin. |
4 |
|
svs.pin.maximum.length |
Sets the maximum length for a pin. |
4 |
|
svs.pin.retrys |
Sets the number of retry attempts |
3 |
|
givex.user.id |
User id provided by Givex. |
|
|
givex.user.id.iv |
Encrypted password initialization vector. |
|
|
givex.password |
Password provided by Givex. |
|
|
givex.password.iv |
Encrypted password initialization vector. |
|
|
givex.allow.partial.tender |
Specify whether to allow partial tendering of gift cards. |
true |
|
givex.pin.entry |
Turn on/off the prompting for security pin for Givex Cards. |
false |
|
givex.pin.entry.types |
Sets which tender types require security pin capture. |
73,83 |
|
givex.pin.minimum.length |
Sets the minimum required length for a Givex security pin. |
6 |
|
givex.pin.maximum.length |
Sets the maximum required length for a Givex security pin. |
6 |
|
givex.pin.retrys |
Sets the maximum number of retries allowed. |
3 |
|
crypto.keygenType |
Sets keygen algorithm type. |
AES |
|
crypto.cipherType |
Sets cipher algorithm type. |
AES/CBC/PKCS5Padding |
|
crypto.keySize |
Sets size of the key store. |
128 |
|
crypto.iterations |
Sets number of iterations. |
100000 |
|
crypto.factoryinstance |
Sets crypto factory instance for keystore password encryption. |
PBKDF2WithHmacSHA512 |
|
crypto.secretkeyspec |
Sets crypto secret key spec for keystore password encryption. |
AES |
|
crypto.keystoretype |
Sets keystore type. |
JKS |
crypto.keystoretype = JKS |
crypto.digest |
Sets digest for keystore password. |
SHA-512 |
|
crypto.hashbyteSize |
Sets hash byte size for keystore password. |
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 |
|
line.display.enabled |
Enables line item display on PED. |
false |
|
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,
|
|
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,
|
|
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. |