1. Core Configuration Guide
  2. Adyen

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.

Minimum Version

The Adyen interface requires a minimum EFTLink version of v20.0.

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:

Open a terminal window and change directory to where the script file resides.

For Windows: Type encrypt-adyen.bat –k [<keystore name> <properties file>].

For example, encrypt-adyen.bat –k

For Linux: Type encrypt-adyen.sh –k [<keystore name> <properties file>].

For Example, ./sudo encrypt-adyen.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 (adyen.keystore, adyen.properties) will be used. When creating the adyen.keystore, a companion file adyen.keystore.properties is also created which contains information relating to generating the keystore password.

Password Encryption

The following settings within the adyen.properties file need to be encrypted.

  • adyen.password

To encrypt a password; Open a terminal window and change directory to where the script file resides.

For Windows: Type encrypt-adyen.bat –e <keystore name> <properties file> <password>.

For example, encrypt-adyen.bat –e

*For Linux: Type encrypt-adyen.sh –e [<keystore name> <properties file> <value>].

For example, sudo ./ encrypt-adyen.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 password is included as arguments then the encrypted value and initialization vector will be outputted to the console which must be copied and pasted to adyen.password and adyen.password.iv in adyen.properties.

To re-encrypt; Open a terminal window and change directory to where the script file resides.

For Windows: Type encrypt-adyen.bat –r [<keystore name> <properties file> <keygen type> <cipher type> <key size> <iterations>].

For example, encrypt-adyen.bat –r

*For Linux: Type encrypt-adyen.sh –r [<keystore name> <properties file> <keygen type> <cipher type> <key size> <iterations>].

For example, sudo ./ encrypt-adyen.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/.

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.environment = Live

adyen.merchant.account

Merchant account code provided by Adyen.

adyen.merchant.account = OracleTest

adyen.username

Username provided by Adyen.

adyen.username = [user name]

adyen.password

Encrypted password, see password encryption section for details.

Adyen.password = [encrypted password string]

Adyen.password.iv

Encrypted password initialization vector, see password encryption section for details.

Adyen.password.iv = [encrypted password iv string]

ped.address

IP address of the PED. If serial ped then com port number.

ped.address = IP ADDRESS

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

Pos.name = Oracle

ped.name

Any symbolic name of the PED.

NA

ped.name = VX680_01

merchant.reference

Unique merchant reference.

NA

merchant.reference = Merchant_A

tender.options

Specify tender options to be used. Currently supported options are:

  • AskGratuity
  • AttendantActionHandler
  • BypassPin
  • DontPrintReceipt
  • EnableMagstripeFallback
  • Error
  • ForcedDecline
  • ForcedOnline
  • GetAdditionalData
  • KeyedCardDetailsHandler
  • KeyedEntry
  • NoCTLS
  • NoProcess
  • ReceiptHandler
  • UNKNOWN

NA

tender.options = GetAdditionalData,ReceiptHandler,AttendantActionHandler

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 = auto

tokenized.refund.reversal

Specify whether to allow reversal of tokenized refunds.

false

tokenized.refund.reversal = true

combine.receipt

When combine.receipt is true, sets which line number to suppress.

combine.receipt = true

combine.receipt.suppress.line

When combine.receipt is true, sets which line number to suppress.

combine.receipt.suppress.lines = 1,2,3,4,5

combine.receipt.suppress.string

When combine.receipt is true, sets which line to suppress when strings are matched.

combine.receipt.suppress.lines = Date,Time

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.

pos.id.override = 10

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.

print.all.receiptSets = false

crypto.keygenType

Sets keygen algorithm type.

crypto.keygenType = AES

crypto.cipherType

Sets cipher algorithm type.

crypto.cipherType = AES/CBC/PKCS5Padding

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.keySize = 128

crypto.iterations

Sets number of iterations.

crypto.iterations = 10000

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.type=mx925

Ped.display.lineitems

Enable line display on compatible devices.

true

Ped.display.lineitems=true

Currency symbol

Symbol to use online display for currency.

none

Currency.symbol=$

Screen.name

Line display format screen name.

none

Screen.name=virtual_receipt02.xslt

Screen.update.timeout

Timeout in milliseconds when updating line display.

5000

Screen.update.tmeout=5000

Svc.reference

Used to identify a particular POS/device when performing gift card operations.

none

Svc.reference=TestPED

Svc.cardtype

Identify gift card type in use on the account.

none

Svc.cardtype=examplecard

Log.signature

Log the signature data to the log file. For security, this should be left to false in a production environment.

false

Log.signature=false

Electronic.signature

Enable the extracting of electronic signature from the device for display/approval on the pos.

false

Electronic.signature=true

card.inserted.response.timeout

Timeout for overall transaction after card is inserted.

1200

card.inserted.response.timeout=1200

Void.header.n

[where n is >0]

Specify several header lines to include on void receipts.

none

void.header.1 = **********

void.header.2 = ** VOID **

void.header.3 = **********

Void.footer.n

[where n is >0]

Specify a number of footer lines to include on void receipts.

none

void.footer.1 = **********

void.footer.2 = ** VOID **

void.footer.3 = **********

Override.[giftcardtype].[action]

Overrides the command for a particular gift card type, issuing a custom action code.

none

override.givex.loadType=activate

Currency.default

Used for gift cards, specifies currency code to use.

USD

currency.default =USD

max.attempts.init.library

Specify maximum number of attempts to initialize Adyen's library.

1

max.attempts.init.library=1

max.attempts.init.pos

Specify maximum number of attempts to register POS.

1

max.attempts.init.pos=1

max.attempts.init.ped

Specify maximum number of attempts to register PED.

1

max.attempts.init.ped=1

state.refresh.timeout

Specify time-out (in ms) of PED state refresh.

5000

state.refresh.timeout=5000

register.pos.timeout

Specify time-out (in ms) of POS register.

120000

register.pos.timeout=120000

register.ped.timeout

Specify time-out (in ms) of PED register.

180000

register.ped.timeout=180000

exit.library.timeout

Specify time-out (in ms) of exit library function.

5000

exit.library.timeout=5000

init.library.timeout

Specify time-out (in ms) of init library function.

5000

init.library.timeout=5000

create.tender.cancel.timeout

Specify time-out (in ms) of tender cancel in the event of failure.

10000

create.tender.cancel.timeout=10000

create.specialtender.cancel.timeout

Specify time-out (in ms) of special tender cancel in the event of failure.

10000

create.specialtender.cancel.timeout=10000

pos.message.timeout

Specify time-out (in ms) of responses to POS message display requests.

3000

pos.message.timeout=3000

refresh.ped.status

Specify whether ped status refresh is to be attempted prior to tender operations.

true

refresh.ped.status=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.failcontinue=false

refresh.ped.waitqueue

Specify whether tender process should wait for screen updates to complete before attempting tender/refresh.

false

refresh.ped.waitqueue=false

refresh.ped.callbackonly

Specify whether when checking ped status prior to a tender operation, only the callback information is used.

true

refresh.ped.callbackonly=true

Merchant.reference.format

Specify the format of the merchant reference - replaces static value with a dynamically generated value using a number of substitutions.

See Merchant Reference Formats.

R (use existing static merchant ref)

merchant.reference.format=R-dddddddddd-SSSSSS.WWWWWW.YYYYMMDD.hhmmss.TTTTTT.qq

allow.giftcard.partial.tender

Specify whether to allow partial tendering of gift cards.

true

allow.gift.partial.tender=true

Proxy.url

Specify optional proxy url for use with Adyen library.

none

proxy.url=

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

svc.activate.and.reload=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

#enhanced overrides for svs giftcard commandsoverride.svs.issue.loadType=activate|loadoverride.svs.activate.loadType=activate|loadoverride.svs.reload.loadType=load#enhanced overrides for givex giftcard commandsoverride.givex.issue.loadType=activateoverride.givex.activate.loadType=activateoverride.givex.reload.loadType=load

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

#enhanced overrides for svs giftcard commandsoverride.svs.redeem.redemptionType=override.svs.redeemunload.redemptionType=cashbackoverride.svs.addreversal.redemptionType=override.svs.activatereversal.redemptionType=#enhanced overrides for givex giftcard commandsoverride.givex.redeem.redemptionType=override.givex.redeemunload.redemptionType=override.givex.addreversal.redemptionType=cashbackoverride.givex.activatereversal.redemptionType=cashback|deactivate

card.signature.response.timeout

Specify timeout for prompt on POS display to accept signature in seconds.

300

card.signature.response.timeout=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.pan=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

qrcode.default.expiry=0000

register.ped.include.storeid

Specifies whether to include the StoreId (if provided by the POS) when registering the PED.

true

register.ped.include.storeid=true

CNP.tender.option

Specify tender option to use for customer not present credit/debit cards. Valid options are: MOTO, KeyedEntry.

MOTO

CNP.tender.option=MOTO

identify.merchant.receipts

Specify whether to include the MERCHANT attribute on merchant receipts when sent to the POS.

False

identify.merchant.receipts=false

tokenized.refund.customer.reference

Specify whether to include CustomerReference in tokenized refunds.

False

tokenized.refund.customer.reference=false

tender.reference.authcode

Specify whether to use the TenderReference as the AuthorisationCode if no AuthCode is present.

True

tender.reference.authcode=true

payment.method.override

Override cardType with paymentMethod for use with CardCircuit in cardServiceResponse.

False

payment.method.override=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=OPIV22.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.