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.
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.
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. |
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.
The encryption key must be generated and stored in a keystore. To achieve this, the below steps must be followed:
Note: This section on the creation of the keystore is only applicable if you plan to use Givex as the SVC payment solution, if not then you can ignore this section. |
If using Givex for the SVC payment then configuration requires that the Givex user.id and user.pin to be encrypted within the file tenderretail.properties
.
To achieve this, the following steps must be followed:
To encrypt a password:
Note: For Givex you will need to encrypt the user.id as well as the password so you need to run this section twice - once for user.id and once for password. |
Open a command prompt, and change to the root directory of eftlink.
Type encrypt.bat -r <keystore name> <properties> <encrypted password> <previous initialization vector> <keygen type> <cipher type> <key size> <iterations>
.
For example, encrypt.bat -e tenderretail.keystore tenderretail.properties
[followed by the required password as a final parameter].
Password and initialization vector will be outputted to the console.
Copy and paste it to the appropriate property in tenderretail.properties
.
To re-encrypt a password:
Open a command prompt, and change to the root directory of eftlink.
Type encrypt.bat -e <keystore name> <properties file> <user.id / password>
.
For example, encrypt.bat -r tenderretail.keystore tenderretail.properties [Encrypted password] [Encrypted password iv] AES AES/CBC/PKCS5Padding 128 10000
.
Re-encryption uses existing crypto settings in the properties file to decrypt the password. Once the password is decrypted, a new keystore file is generated using the new crypto parameters specified at the command line and the new encrypted password / initialization vector is generated.
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/ |
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 calledinitializePed.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. |
|
The translation files for this core should not require alteration, but if necessary then this can 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.
The following should have been set in the EftlinkConfig.properties
file by installcore.bat or installcore.sh
EPSCore0=manito.eft.tenderretail.TenderRetailCore
The full set of configuration properties is defined and commented in tenderretail.properties
.
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 |
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 has to 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 a number of header lines to include on void receipts (maximum of 3 supported lines). |
None |
|
Void.footer.n [where n is >0] |
Specify a number of 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 |
|
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 transactions. |
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 |
|
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 |
|
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. |
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. |