4 Cayan
This Cayan implementation is for use with Genius terminals in the US, with communication based on a web service protocol.
EFTLink General
See also the EFTLink general deployment guide if not already familiar with EFTLink.
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
Cayan Genius is deployed as an intelligent terminal. EFTLink connects directly to the terminal using a proprietary web services protocol.
Genius 5.0 and later versions supports a HTTPS interface in addition to its traditional HTTP interface. Only the protocol scheme (https vs. http) and port (8443 vs 8000) differ. The Cayan core can communicate with the Genius device using TLS to secure the connection. The terminal will generate appropriate certificates as required in order to serve the TLS connection, and all certificates generated by the terminal will be signed by the Cayan CA.
The Cayan certificate is automatically stored upon start up in the file cayan.public.jks
To enable TLS in cayan.properties, change all the http.action entries
containing http://cedIp:cedPort
into https://cedIp:cedPort
and set ced.port=8443
Fileset
In addition to standard EFTLink files:
-
cayancore.jar
– executable code for the Cayan EFTLink core -
cayanTA.crt
– Cayan root certificate -
cayan.properties
– configuration settings to specify which features are enabled and to define communication parameters for the interface with the terminal -
langEN_cayan.properties
– English translation file for the Cayan core -
cayanruntime.properties
– core logging settings that are automatically reloaded at runtime (checked every 10 seconds) -
cayandynamic.properties
– merchant specific details that can be accessed through the administration functions -
cayan_receipt.properties
– links a receipt template file to a ReceiptType XML element -
cayan_giftadd_receipt, cayan_giftbalance_receipt, cayan_payment_receipt, cayan_refund_receipt, cayan_reversal_receipt
– customer configurable receipt template files
Runtime files
-
cayan.public.jks
– keystore file containing the Cayan root certificate to allow TLS communication -
cayan.secure
– storage file for the random encryption key that is used to protect merchant information
JRE
Currently the Cayan core is limited to running using JRE 1.8, due to components being deprecated or removed in java versions 9 to 11.
The POS may be issued with a later java version, adding an additional requirement to install 2 JRE versions - one for the POS system, and a second separate JRE 1.8 for EFTLink.
Please see the Oracle Retail EFTLink Framework Installation and Configuration Guide for details on providing the location for the JRE when running EFTLink.
Account Information Entry
At initial software start up, a keystore is created for encryption information and the Cayan certificate is placed into a second keystore. Account information is added to the EFTLink system via the EFTLink admin menus. Five parameters are required to be entered via the admin function:
-
Account Name
-
Account Software Key
-
Site Identifier
-
Account DBA
-
Terminal Identifier
Both the Account Name and Account Software Key are automatically
encrypted. All 5 parameters are held in the cayandynamic.properties
file.
See the Supported Functions section below for entry of the parameters.
Account Information Re-Encryption
The password within the cayandynamic.properties
file needs to be encrypted. To achieve this, the following steps must be followed:
Windows Operating Systems
To re-encrypt a password with new encryption settings; open a command prompt and change directory to eftlink's location.
-
Type:
encrypt-cayan.bat -g [<keystore name> <properties> <certificate> <dyanamicProperties> {<Colon-Separated List of Properties>} <keygenType> <cipherType> <keySize> <iterations>]
.For example,
encrypt-cayan.bat -g
-
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.
-
When using AES algorithm with a key size 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/
Linux Systems
Note:
You may be required to give script file(s) execution rights. This can be accomplished by opening a terminal window and typing:
sudo chmod
+x <PathToFile>
for example, sudo chmod
+x /opt/eftlink/encrypt-cayan.sh
To re-encrypt a password with new encryption settings; open a command prompt and change directory to eftlink location.
-
Type at the command prompt:
sudo ./encrypt-cayan.sh -g [<keystore name> <properties> <certificate> <dyanamicProperties> {<Colon-Separated List of Properties>} <keygen type> <cipher type> <key size> <iterations>]
.For example,
sudo ./encrypt-cayan.sh -g
-
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.
-
When using AES algorithm with a key size 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/
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.cayan.CayanCore
Configuration Settings
The full set of configuration properties is defined and commented in cayan.properties
.
Key Settings
Settings that may be different for each POS/PED.
Table 4-1 Cayan - Key Settings
Setting | Description | Example |
---|---|---|
Terminal address |
IP of Genius terminal. |
|
Simulator |
Simulation mode. |
|
Receipt handling |
Separate EFT receipts or EFT receipt as part of the regular POS receipt. |
|
Signature Verification |
Enable/Disable signature verification dialog. |
|
Reversal Failure |
Enable/Disable reversal failure dialog. |
|
Secondary Settings
These settings are normally correct at their default values but can be overridden if necessary.
Table 4-2 Cayan - Secondary Settings
Setting | Description | Default | Example |
---|---|---|---|
Terminal address |
Port number. |
8080 for http and 8443 for https. |
|
Timeout |
Overall response timeout in seconds. |
600 |
|
Status Timeout |
Timeout period for checking status of device. |
1 |
|
LineItem Timeout |
Timeout period for outputting a line item to the device. |
1 |
|
Signature display scaling |
Signature display scaling. |
3 |
|
Status Checks |
Perform periodic status checks during a transaction. |
false |
|
Status Check On Demand |
Perform status check at the end of transaction. |
false |
|
Auto Reversal |
Not used |
false |
|
statusMngr |
Interval of periodic status checks when not in a transaction. |
2 |
|
Admin menu |
Specifies the admin menu configuration. |
NA |
|
Maintenance Timeout |
Timeout for maintenance menu. |
60 |
|
Operator Response Timeout |
Operator prompt timeout on POS. |
60 |
|
Signature Scaling |
Used to scale the signature from the CED for displaying on the POS. |
3 |
|
Signature MaxY |
Specifies the maximum size of the signature to be scaled. |
100 |
|
Signature Verification |
Determines whether the signature will be verified on the POS if returned from the device. |
true |
|
Receipt Handling |
Embed the receipt in the card service response. |
false |
|
Sale Receipt |
Send sale receipt to POS for printing. |
true |
|
Gift Receipt |
Send gift receipt to POS for printing. |
true |
|
Reversal Msg |
Not USED - prompt for reversal on test system |
false |
|
Status Interval |
Interval of periodic status checks when in a transaction. |
2 |
|
Auto Report |
Not USED. |
false |
|
Terminal Response Timeout |
Timeout used when waiting for terminal to become idle at start of order. |
10 |
|
Proxy Timeout |
Timeout to connect in seconds to Cayan web service. |
5 |
|
Proxy Host |
Host name to use as a proxy. |
none |
|
Proxy Port |
Port to use when using a proxy. |
none |
|
Allow Duplicate in Request |
Specify the value for the AllowDuplicate field in the StageTransaction Request. |
false |
|
Line Display Maximum Length |
Specify maximum number of characters per line on the line display |
35 |
|
Accept button label |
Specify the label of the Agree or Accept button in a customer question/verification custom form. |
YES |
|
Decline button label |
Specify the label of the decline button in a customer question/verification custom form. |
NO |
|
Mask Customer Input |
Specify whether to mask the customer's input in the PED for custom form. |
false |
|
Customer Input Max Length |
Maximum number of characters when capturing data from the CED. |
30 |
|
Phone Number Max Length |
Maximum number of characters for phone capture. |
10 |
|
Customer Input Guidance Text Max Length |
Maximum length of additional guidance text explaining what information the customer should enter. |
144 |
|
Customer Input Label Max Length |
Maximum length of the label above the text entry box on the Genius device. |
36 |
|
Cancellable Input Types |
A comma separated list of input types for custom forms that are cancellable. |
SIGNATURE |
|
Line Item Display Version |
Specify the version of the routines used to update the line display on the cayan device. The latest version 4 includes the tenders on the line display. 1 Original implementation redraw all lines 2 Handle discounted items without redrawing all lines 3 Redraw on discount due to synchronization problems 4 As 3, with added display of tenders |
4 |
ced.item.update.mode=4 |
Administration Functions
The terminal has some administration/maintenance functions. These are normally invoked from a dedicated EFT Maintenance button.
EFTLink uses DeviceProxy messages to display input prompts on the POS to manage these functions.
Cayan will provide the merchant credentials that are required to setup the connection with the Cayan host. The information consists of five elements: Name, Key, SiteID, DBA, and TerminalID.
These credentials must be entered through the administration functions. The information is stored in the file cayandynamic.properties
. The fields Name and Key are stored in an encrypted form. For each POS system, the Cayan core will create a random encryption key to protect sensitive information. The encryption key itself is stored in the file cayan.secure using an EFTLink specific encryption algorithm.
Cayan has created an Oracle account for testing purposes. To connect to the Cayan host from non-US IP addresses, a 'WhitelistRequest' document containing the static IP of the Genius terminal must be sent to Cayan first. It typically takes 2-3 business days for Cayan security to review and then IT to process.
Table 4-3 Cayan - Administration Functions
Functions | Description |
---|---|
Merchant Name |
This operation allows the technician/cashier to enter the merchant name and store it encrypted in |
Merchant Key |
This operation allows the technician/cashier to enter the merchant key and store it encrypted in |
Merchant Site ID |
This operation allows the technician/cashier to enter the merchant site identifier and store it in |
Merchant DBA |
This operation allows the technician/cashier to enter the merchant dba and store it in |
Merchant Terminal ID |
This operation allows the technician/cashier to enter the merchant terminal identifier and store it in |
Supported Functions
Below is a list of supported functionalities of the interface to Cayan.
Table 4-4 Cayan - Supported Functions
Function | Description |
---|---|
Payment |
Sends payment request to the terminal. Terminal will return a response message with receipt strings. |
Reversal |
Sends reversal request to the terminal. This will reverse a transaction specified by the transaction number, found on the receipt, which must be captured by the POS and pass on to EFTLink. |
Refund |
Sends refund request to the terminal. This will refund a transaction with specified amount. |
Sale State Notifications |
Sends line items through to the device so the customer display can be updated in line with the POS. |
SVC Payment |
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 Activate |
Sends a gift or merchandise credit card activation request to the terminal. |
SVC Deactivate |
Sends a gift or merchandise credit card deactivation request to the terminal. The account is disabled after this as the request is intended to be used for lost or stolen cards. It is not possible to use the card or account once this request has been issued and accepted. |
SVC Add Value |
Sends a gift or merchandise credit card add value request to the terminal. This will only add value to an account that has been activated. |
SVC Balance Enquiry |
Sends a gift or merchandise credit card balance enquiry request to the terminal. |
SVC Unload (Cashout) |
Sends a gift or merchandise credit card cash out request to the terminal. 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. |
Custom form for customer question/verification |
Sends a request to the terminal with a question/verification message. The customer selects either the Yes or No button. The core sends 'Y' or 'N' as part of the response to the POS. |
Custom form for capturing phone number |
Sends a request to the terminal triggering a phone number capture. The customer keys in their phone number and selects Submit. The core sends the captured phone number to the POS. |
Custom form for capturing date |
Sends a request to the terminal to capture a date, for example a birth date. The customer keys in their birth date and selects Submit. The core sends the captured date to the POS. |
Custom form for signature capture |
Sends a request to the terminal to capture signature. The customer signs and selects Accept. The core sends the decoded signature to the POS. |