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.

Minimum Version

The Cayan interface requires a minimum EFTLink version 17.0.1.

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 startup 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 startup, 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.bat -g <keystore name> <properties> <certificate> <dyanamicProperties> {<Colon-Separated List of Properties>} <keygenType> <cipherType> <keySize> <iterations>.

For example, encrypt.bat -g cayan.secure cayan.properties cayan.public.jks cayandynamic.properties {merchant.name:merchant.key} 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.
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 accomplish by opening a terminal window and typing:

sudo chmod +x <PathToFile>

for example, sudo chmod +x /opt/eftlink/encrypt.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.sh -g <keystore name> <properties> <certificate> <dyanamicProperties> {<Colon-Separated List of Properties>} <keygen type> <cipher type> <key size> <iterations>.

For example, sudo ./encrypt.sh -g cayan.secure cayan.properties cayan.public.jks cayandynamic.properties {merchant.name:merchant.key} 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.
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 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.	`ced.ip = IP ADDRESS`
Simulator	Simulation mode.	`ced.simulator = false`
Receipt handling	Separate EFT receipts or EFT receipt as part of the regular POS receipt.	`EmbeddedReceipt = false`
Signature Verification	Enable/Disable signature verification dialog.	`SignatureVerification = false`
Reversal Failure	Enable/Disable reversal failure dialog.	`ReversalDialog = false`

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.	`ced.port =`
Timeout	Overall response timeout in seconds.	600	`ced.get.timeout =`
Status Timeout	Timeout period for checking status of device.	1	`ced.status.timeout`
LineItem Timeout	Timeout period for outputting a line item to the device.	1	`ced.item.timeou`t
Signature display scaling	Signature display scaling.	3	`SignatureScaling =`
Status Checks	Perform periodic status checks during a transaction.	false	`ced.statuschecks = false`
Status Check On Demand	Perform status check at the end of transaction.	false	`ced.statuschecks.ondemand = false`
Auto Reversal	Not used	false	`ced.abortautoreversal = false`
statusMngr	Interval of periodic status checks when not in a transaction.	2	`ced.status.interval.inactive = 2`
Admin menu	Specifies the admin menu configuration.	NA	`AdminMenu =`
Maintenance Timeout	Timeout for maintenance menu.	60	`MaintenanceTimeout = 60`
Operator Response Timeout	Operator prompt timeout on POS.	60	`OperatorTimeout = 60`
Signature Scaling	Used to scale the signature from the CED for displaying on the POS.	3	`SignatureScaling = 3`
Signature MaxY	Specifies the maximum size of the signature to be scaled.	100	`SignatureMaxY = 100`
Signature Verification	Determines whether the signature will be verified on the POS if returned from the device.	true	`SignatureVerification = true`
Receipt Handling	Embed the receipt in the card service response.	false	`EmbeddedReceipt = false`
Sale Receipt	Send sale receipt to POS for printing.	true	`EmbeddedReceiptSale = true`
Gift Receipt	Send gift receipt to POS for printing.	true	`EmbeddedReceiptGift = true`
Reversal Msg	Not USED - prompt for reversal on test system	false	`ReversalDialog = false`
Status Interval	Interval of periodic status checks when in a transaction.	2	`ced.status.interval = 2`
Auto Report	Not USED.	false	`auto.report = false`
Terminal Response Timeout	Timeout used when waiting for terminal to become idle at start of order.	10	`ced.wait.idle.timeout=10`
Proxy Timeout	Timeout to connect in seconds to Cayan web service.	5	`cayan.service.connect.timeout=5`
Proxy Host	Host name to use as a proxy.	none	`https.proxyHost=adc-proxy.example.com`
Proxy Port	Port to use when using a proxy.	none	`https.proxyPort=80`
Allow Duplicate in Request	Specify the value for the AllowDuplicate field in the StageTransaction Request.	false	`Allowduplicate=false`
Line Display Maximum Length	Specify maximum number of characters per line on the line display	35	`ced.item.linelength = 35`
Accept button label	Specify the label of the Agree or Accept button in a customer question/verification custom form.	YES	`CustQuestionYesLabel=YES`
Decline button label	Specify the label of the decline button in a customer question/verification custom form.	NO	`CustQuestionNoLabel=NO`
Mask Customer Input	Specify whether or not to mask the customer's input in the PED for custom form.	false	`MaskCustomerInput=false`
Customer Input Max Length	Maximum number of characters when capturing data from the CED.	30	`GetCustomerInputMaxLength=30`
Phone Number Max Length	Maximum number of characters for phone capture.	10	`GetPhoneNumberMaxLength=10`
Customer Input Guidance Text Max Length	Maximum length of additional guidance text explaining what information the customer should enter.	144	`GetCustomerInputGuidanceTextMaxLength=144`
Customer Input Label Max Length	Maximum length of the label above the text entry box on the Genius device.	36	`GetCustomerInputLabelMaxLength`
Cancellable Input Types	A comma separated list of input types for custom forms that are cancellable.	SIGNATURE	`CancellableInputTypes = 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 `cayandynamic.properties`.
Merchant Key	This operation allows the technician/cashier to enter the merchant key and store it encrypted in `cayandynamic.properties`.
Merchant Site ID	This operation allows the technician/cashier to enter the merchant site identifier and store it in `cayandynamic.properties`.
Merchant DBA	This operation allows the technician/cashier to enter the merchant dba and store it in `cayandynamic.properties`.
Merchant Terminal ID	This operation allows the technician/cashier to enter the merchant terminal identifier and store it in `cayandynamic.properties`.

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.