| Oracle® Retail EFTLink Core Configuration Guide Release 18.0 F12262-04 |
|
 Previous |
 Next |
This chapter describes the procedures to set up EFTLink to interface with Adyen.
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.
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.
EFTLink connects to Adyen's PED, via JNI wrapper.
|
Note: This document does not cover installation of Adyen software. |
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.
The encryption key must be generated and stored in a keystore. To achieve this, the following steps must be followed:
The password within the adyen.properties file needs to be encrypted. To achieve this, the following steps must be followed:
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 and adyen.password.iv in adyen.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/
|
Note: You may be required to give script file(s) execution rights. This can be accomplish by opening a terminal window and typing:" for example, |
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 and adyen.password.iv in adyen.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/
|
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.
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.adyen.AdyenCore
The full set of configuration properties is defined and commented in adyen.properties.
Settings that may be different for all POSs.
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. |
|
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. 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: AskGratuity AttendantActionHandler BypassPin DontPrintReceipt EnableMagstripeFallback Error ForcedDecline ForcedOnline GetAdditionalData KeyedCardDetailsHandler KeyedEntry NoCTLS NoProcess ReceiptHandler UNKNOWN |
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 |
|
|
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 specify ID. Should be used in PED POOL mode. |
|
|
|
cashback |
Enables cashback. The following options are supported: off - no cashback pos - POS will prompt for cashback options via DeviceRequest ped - PED will prompt for cashback options via its display. |
|
|
|
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. |
[will auto-detect] |
|
|
Ped.display.lineitems |
Enable line display on compatible devices. |
true |
|
|
Currency symbol |
Symbol to use on line 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 a number of 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. |
true |
|
|
refresh.ped.waitqueue |
Specify whether tender process should wait for screen updates to complete before attempting tender/refresh. |
false |
|
|
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 |
|
|
max.credit.installments.number |
Specify maximum number of installments. |
1 |
|
|
min.credit.installments.value |
Specify minimum installment value. |
0 |
|
|
prompt.credit.installments.timeout |
Specify credit installments prompt timeout in seconds. |
60 |
|
|
prompt.credit.debit |
Specify credit debit prompt. |
false |
|
|
prompt.credit.debit.timeout |
Specify credit debit prompt timeout in seconds. |
60 |
|
|
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.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 |
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:
Example format:
R-dddddddddd-SSSSSS_WWWWWW.YYYYMMDD.hhmmss.TTTTTT.qq
Where gift card functionality is enabled and the full gift card PAN is required to be returned to the POS. Ensure the CardRange.xml is 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.
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 overtendering 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 overtendering 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. |
