2 Adyen
This chapter describes the procedures to set up EFTLink to interface with Adyen.
Disambiguation
This core implementation is for use with Adyen JNI wrapper with communication based on a socket or serial protocol, implemented internally within the JNI, to the terminal.
EFTLink General
See also 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.
System Architecture
EFTLink connects to Adyen's PED, via JNI wrapper.
Note:
This document does not cover installation of Adyen software.
Fileset
In addition to standard EFTLink files, Adyen uses:
-
cores/Adyen/AdyenCore.jar
– executable code for the Adyen EFTLink core. -
adyen.properties
– configuration settings to specify which features are enabled and to define communication parameters for the interface with the EFT payment system. -
data/adyen.keystore
– keystore file to encrypt a password in adyen.properties, this file need to be generated at installation. 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:
Password Encryption
The password within the adyen.properties
file needs to be encrypted. To achieve this, the following steps must be followed:
Windows Operating Systems
To encrypt a password; open a command prompt and change directory to eftlink's location.
-
Type
encrypt.bat –e <keystore name> <properties file> <password>
.For example,
encrypt.bat –e adyen.keystore adyen.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
adyen.password
andadyen.password.iv
inadyen.properties
.
To re-encrypt a password with new encryption settings; open a command prompt and change directory to eftlink's location.
-
Type
encrypt.bat –r <keystore name> <properties> <encrypted password> <previous initialization vector> <keygen type> <cipher type> <key size> <iterations>.
For example,
encrypt.bat –r adyen.keystore adyen.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.
-
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/
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 encrypt a password; open a terminal window and change directory to eftlink's location.
-
Type:
sudo ./encrypt.sh -e <keystore name> <properties> <password>.
For example,
sudo ./encrypt.sh -e adyen.keystore adyen.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
adyen.password
andadyen.password.iv
inadyen.properties
.
To re-encrypt a password with new encryption settings; open a command prompt and change directory to eftlink location.
-
Type:
sudo ./encrypt.sh -r <keystore name> <properties> <encrypted password> <previous initialization vector> <keygen type> <cipher type> <key size> <iterations>
.For example,
sudo ./encrypt.sh -r adyen.keystore adyen.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.
-
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/
Third Party
Note:
Critically important
The following file is also needed, not supplied by Oracle:
POS_JNI32.jar/POS_JNI64.jar
is a JNI wrapper supplied by Adyen to allow communication to Adyen's PED.
Use the appropriate version according to VM environment, POS_JNI32.jar
for 32-bit operating systems and POS_JNI64.jar
for 64-bit operating systems.
Once identified, the file should be placed in cores\Adyen
alongside AdyenCore.jar
and renamed POS_JNI.jar
.
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.adyen.AdyenCore
Configuration Settings
The full set of configuration properties is defined and commented in adyen.properties
.
Key Settings
Settings that may be different for all POS’s.
Table 2-1 Adyen - Key Settings
Setting | Description | Example |
---|---|---|
adyen.environment |
Live or Test environment. Default is Test. |
|
adyen.merchant.account |
Merchant account code provided by Adyen. |
|
adyen.username |
Username provided by Adyen. |
|
adyen.password |
Encrypted password, see password encryption section for details. |
|
Adyen.password.iv |
Encrypted password initialization vector, see password encryption section for details. |
|
ped.address |
IP address of the PED. If serial ped then com port number. |
|
Secondary Settings
These settings are normally correct at their default values but can be overridden if necessary.
Table 2-2 Adyen - Secondary Settings
Setting | Description | Default | Example |
---|---|---|---|
pos.name |
Name of the Integrator POS. (symbolic name of the POS for example, POS123). Optional. |
NA |
|
ped.name |
Any symbolic name of the PED. |
NA |
|
merchant.reference |
Unique merchant reference. |
NA |
|
tender.options |
Specify tender options to be used. Currently supported options are:
|
NA |
|
tokenized.refund |
Enables refund by token if set to true or auto. If set to false, standard refund will always be performed. If set to auto, tokenized refund will be performed if a token is supplied in the request otherwise standard refund will be used. |
auto |
|
tokenized.refund.reversal |
Specify whether to allow reversalof tokenized refunds. |
false |
|
combine.receipt |
When combine.receipt is true, sets which line number to suppress. |
|
|
combine.receipt.suppress.line |
When combine.receipt is true, sets which line number to suppress. |
|
|
combine.receipt.suppress.string |
When combine.receipt is true, sets which line to suppress when strings are matched. |
|
|
pos.id.override |
Overrides POS ID from the POS with a specific ID rather than using pos supplied ID. This is required when EFTLink is running multiplexing or in PEDPool mode. Note that the value needs to be the same across all instances hosted in the multiplexer unless otherwise stated by Adyen. |
|
|
print.all.receiptSets |
When set to true, enables all receipts sent from Adyen to be printed. When set to false, prints only the latest receipt set. |
|
|
crypto.keygenType |
Sets keygen algorithm type. |
|
|
crypto.cipherType |
Sets cipher algorithm type. |
|
|
crypto.keySize |
Sets size of the keystore. Note: When keysize is greater than 128, you may get java.security.InvalidKeyException: Illegal key size or default parameters. If this happens you will need to download additional Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files and extract those files to $JAVA_HOME/jre/lib/security/ |
|
|
crypto.iterations |
Sets number of iterations. |
|
|
ped.type |
Override auto-detected ped type to alter ped functionality. Supported values: vx680, vx820, mx900, mx925, E355, P400, V400M, V400CPLUS, VX690, P400PLUS, M400, E285 Note: Line display is enabled only on devices: mx900, mx925, and M400 |
[will auto-detect] |
|
Ped.display.lineitems |
Enable line display on compatible devices. |
true |
|
Currency symbol |
Symbol to use online display for currency. |
none |
|
Screen.name |
Line display format screen name. |
none |
|
Screen.update.timeout |
Timeout in milliseconds when updating line display. |
5000 |
|
Svc.reference |
Used to identify a particular POS/device when performing gift card operations. |
none |
|
Svc.cardtype |
Identify gift card type in use on the account. |
none |
|
Log.signature |
Log the signature data to the log file. For security, this should be left to false in a production environment. |
false |
|
Electronic.signature |
Enable the extracting of electronic signature from the device for display/approval on the pos. |
false |
|
card.inserted.response.timeout |
Timeout for overall transaction after card is inserted. |
1200 |
|
Void.header.n [where n is >0] |
Specify several header lines to include on void receipts. |
none |
|
Void.footer.n [where n is >0] |
Specify a number of footer lines to include on void receipts. |
none |
|
Override.[giftcardtype].[action] |
Overrides the command for a particular gift card type, issuing a custom action code. |
none |
|
Currency.default |
Used for gift cards, specifies currency code to use. |
USD |
|
max.attempts.init.library |
Specify maximum number of attempts to initialize Adyen's library. |
1 |
|
max.attempts.init.pos |
Specify maximum number of attempts to register POS. |
1 |
|
max.attempts.init.ped |
Specify maximum number of attempts to register PED. |
1 |
|
state.refresh.timeout |
Specify time-out (in ms) of PED state refresh. |
5000 |
|
register.pos.timeout |
Specify time-out (in ms) of POS register. |
120000 |
|
register.ped.timeout |
Specify time-out (in ms) of PED register. |
180000 |
|
exit.library.timeout |
Specify time-out (in ms) of exit library function. |
5000 |
|
init.library.timeout |
Specify time-out (in ms) of init library function. |
5000 |
|
create.tender.cancel.timeout |
Specify time-out (in ms) of tender cancel in the event of failure. |
10000 |
|
create.specialtender.cancel.timeout |
Specify time-out (in ms) of special tender cancel in the event of failure. |
10000 |
|
pos.message.timeout |
Specify time-out (in ms) of responses to POS message display requests. |
3000 |
|
refresh.ped.status |
Specify whether ped status refresh is to be attempted prior to tender operations. |
true |
|
refresh.ped.failcontinue |
Specify whether tender will continue if ped status refresh fails or ped is not ready. Note: Originally implemented as true, now false. |
false |
|
refresh.ped.waitqueue |
Specify whether tender process should wait for screen updates to complete before attempting tender/refresh. |
false |
|
refresh.ped.callbackonly |
Specify whether when checking ped status prior to a tender operation, only the callback information is used. |
true |
|
Merchant.reference.format |
Specify the format of the merchant reference - replaces static value with a dynamically generated value using a number of substitutions. |
R (use existing static merchant ref) |
|
allow.giftcard.partial.tender |
Specify whether to allow partial tendering of gift cards. |
true |
|
Proxy.url |
Specify optional proxy url for use with Adyen library. |
none |
|
svc.activate.and.reload |
Specifies whether gift card activation and reload maps to its own function rather than using load. The standard override settings for loadType are NOT used when set to true, and instead the issue, activate and reload Types are used. |
false |
|
Override.[giftcardtype].[action].loadType |
Used when svc.activate.and.reload is true, these settings override the command for a particular gift card type/action, issuing a custom action code. Gift card type may be: svs givex
Action may be: issue activate reload |
none |
|
Override.[giftcardtype].[action].redemptionType |
Used when svc.activate.and.reload is true, these settings override the redemption command for a particular gift card type/action, issuing a custom action code. Gift card type may be: svs givex
Action may be: redeem redeemunload addreversal activatereversal |
none |
|
card.signature.response.timeout |
Specify timeout for prompt on POS display to accept signature in seconds. |
300 |
|
qrcode.default.pan |
When using a method of payment which is performed using a QR code, and does not return a card pan, specify the default pan to be returned in the transaction. Must be numeric. |
0000000000000000 |
|
qrcode.default.expiry |
When using a method of payment which is performed using a QR code, and does not return an expiry date, specify the default expiry date to be returned in the transaction. Must be numeric. |
0000 |
|
register.ped.include.storeid |
Specifies whether to include the StoreId (if provided by the POS) when registering the PED. |
true |
|
CNP.tender.option |
Specify tender option to use for customer not present credit/debit cards. Valid options are: MOTO, KeyedEntry. |
MOTO |
|
identify.merchant.receipts |
Specify whether to include the MERCHANT attribute on merchant receipts when sent to the POS. |
False |
|
tokenized.refund.customer.reference |
Specify whether to include CustomerReference in tokenized refunds. |
False |
|
tender.reference.authcode |
Specify whether to use the TenderReference as the AuthorisationCode if no AuthCode is present. |
True |
|
payment.method.override |
Override cardType with paymentMethod for use with CardCircuit in cardServiceResponse. |
False |
|
Merchant Reference Formats
For the merchant reference format, the following substitutions are available:
Table 2-3 Merchant Reference Formats
Component | Description | Example | Format |
---|---|---|---|
R |
Use existing Merchant Reference |
R |
|
S |
StoreID |
SSSSSS |
min 3, max 10 chars, left 0 filled |
W |
WorkStation id |
WWWWWW |
min 3, max 20 chars, left 0 filled |
YY |
Year |
YY or YYYY |
extracted from POSTimeStamp |
MM |
Month |
MM |
extracted from POSTimeStamp |
DD |
Day |
DD |
extracted from POSTimeStamp |
hh |
Hour |
hh |
extracted from POSTimeStamp |
mm |
Minute |
mm |
extracted from POSTimeStamp |
ss |
Second |
ss |
extracted from POSTimeStamp |
T |
Transaction number |
TTTTTT |
min 3, max 20 chars, left 0 filled |
d |
Transaction date |
dddddddddd |
must be 10 chars |
The following special characters are also allowed:
- minus -
- underscore _
- period .
Example format:
R-dddddddddd-SSSSSS_WWWWWW.YYYYMMDD.hhmmss.TTTTTT.qq
Gift Card Configuration
For EFTLink to return the PAN of a gift card then a CardRange.xml file is required. The CardRange.xml needs to be correctly configured to include the gift card range, with the attribute ClearTextPAN set to true.
This will also ensure that any gift card request sent from the POS will be confirmed as a valid gift card request and will be processed.
For example,
<CardTypeAttributes CardType = "80" ClearTextPAN="true"
<Range Start="4321+" End="4329+" Name="SVS_GIFT_CARD"
Core="0" CardType="80"/>
Migration to OPIRetail Core
Once Adyen core is installed and functional, the migration to OPIRetail core requires a small number of additional steps initially.
Follow the separate guide for OPIRetail core installation. This primarily consists of the following steps:
Step | Action |
---|---|
OPIRetail Core installed |
Performed using the command Installcore opiretail |
OPIRetail.properties updated |
See section on OPIRetail.properties below. |
The following settings are required to be updated in the standard file to communicate with the PED.
Filename | Setting |
---|---|
OPIRetail.properties |
EPSAddress = [ip address of ped] EPSPort=8443 ProxyInfo=OPIV19.1 POSInfo=X-Store |
Following installation the eftlink.properties file will show the installed OPIRetail core:
Filename | Setting |
---|---|
EFTLinkConfig.properties |
EPSCore0 = oracle.eftlink.opiretail.OPIRetailCore |
Note:
The cardserviceresponse message content when using adyen and OPIRetail cores does differ in some fields. Obtain Adyencore and OPIRetail responses for comparison.
Rollback Process
If all steps above have been followed, both adyencore and OPIRetail cores are installed.
It is then possible to easily switch between the 2 cores by altering the parameter in EFTLinkConfig.properties. Restart EFTLink once the parameter has been altered and saved.
To use Adyen Core:
Filename | Setting |
---|---|
EFTLinkConfig.properties |
EPSCore0 = manito.eft.adyen.AdyenCore |
Check the log file to ensure that the correct core is in use:
09:57:14,521 [OPIMessageServer MessageEvent[614505366]] (log.EPSLogger:786) INFO - EF/6690 Core AdyenCore v19.0.1.5 20200325-1446 initialised
09:57:14,531 [OPIMessageServer MessageEvent[614505366]] (log.EPSLogger:786) INFO - EF/6690 Core AdyenCore/AdyenCore v19.0.1.5 20200325-1446 initialised as core 0
To use OPIRetail Core:
Filename | Setting |
---|---|
EFTLinkConfig.properties |
EPSCore0 = oracle.eftlink.opiretail.OPIRetailCore |
Check the log file to ensure that the correct core is in use:
09:51:12,027 [OPIMessageServer MessageEvent[850967262]] (log.EPSLogger:786) INFO - EF/6355 Core OPIRetailCore v19.0.1.21 20200325-1446 initialised09:51:12,032 [OPIMessageServer MessageEvent[850967262]] (log.EPSLogger:786) INFO - EF/6355 Core OPIRetailCore/OPIRetailCore v19.0.1.21 20200325-1446 initialised as core 0
Supported Functions
Below is a list of supported functionalities of the interface to Adyen. Some functions provided by Adyen, such as Loyalty, Cashback and so on, are not implemented in this release because of the business requirement.
Table 2-4 Supported Functions
Function | Description |
---|---|
Payment |
EFTLink sends payment requests to Adyen. Adyen will return a response message with unformatted receipt strings for customer and/or merchant receipts. If successful, appropriate receipts will be printed at the end of transaction. |
Reversal |
EFTLink sends reversal requests to Adyen. 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 |
EFTLink sends refund requests to Adyen. This will refund a transaction with specified amount. |
Tokenized Refund |
EFTLink sends refund requests to Adyen. This will refund a transaction with specified token id. |
SVC Payment |
Sends a gift or merchandise credit card payment request to the terminal. If there are not enough funds available and over tendering is supported by the gift card provider, then only the funds available will be deducted. The POS client will have to settle the transaction with another tender in this scenario. If over tendering is not supported by the provider, the transaction will be rejected with 'insufficient funds'. |
SVC Payment reversal |
Sends a gift or merchandise credit card activation request to the terminal. |
SVC Add Value |
Sends a gift or merchandise credit card add value request to the terminal. This does not require prior card activation. |
SVC Add reversal |
Sends a gift or merchandise credit card payment request to the terminal. |
SVC Unload (Cash Out) |
Sends a gift or merchandise credit card payment request to the terminal. All funds available on the card are deducted from the account and the cash value returned to the POS. The account can be optionally deactivated by configuration. |
SVC Balance Enquiry |
Sends a gift or merchandise credit card balance enquiry request to the terminal. |
Sale State Notifications |
Sends line items through to the device so the customer display can be updated in line with the POS. |