This document covers EFTLink Integration with Oracle Payment Interface (OPI) Payment Systems. It should be read in conjunction with the Oracle Retail EFTLink Framework Installation and Configuration Guide.
Note: To avoid confusion references to OPI Retail or similar phrasing refers to Oracle Payment Interface and not Open Payment Initiative. |
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 the OPI using only a secure HTTPS connection (using HTTP POST), and uses a Transport Layer Security (TLS) protocol version 1.2 or higher.
The following files are used in the EFTLink folder:
cores/opiretail/opiretail.jar
opiretail.properties
(optional, if not present defaults apply)
Lang<CC>_<Core>.properties
– Language translation file, for further information see 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.
The following should have been set in the EftlinkConfig.properties
file by installcore.bat or installcore.sh:
EPSCore0= oracle.eftlink.opiretail.OPIRetailCore
The full set of configuration properties is defined and commented in opiretail.properties
.
Settings that may be different for each POS.
Table 6-1 OPI - Key Settings
Setting | Description | Default | Example |
---|---|---|---|
EPSAddress |
Specifies the host address of the Oracle Payments Interface service. |
localhost |
|
EPSPort |
Specifies the host port of the Oracle Payments Interface service. |
5007 |
|
DetectReceiptSignatureString |
Specifies the text to find in the print data returned from the Oracle Payments Interface response in order to determine whether a signature check prompt is required for the request. |
Signature |
|
DefaultOperatorId |
Specifies a default operator id for POS systems that do not provide an operator id in the EPSRequest. |
EFTLink OPI Operator |
|
DefaultBaseCurrency |
Specifies the default base currency to be used as part of the TransCurrency element in the OPI Retail messages. |
GBP |
|
DefaultCheckType |
Specifies the default check type for check processing. |
01 |
|
DefaultCheckName |
Specifies the default check name for check processing. |
Personal Check |
|
SiteId |
Specifies the SiteId data which is required in every Oracle Payments Interface request. |
null |
|
ProxyInfo |
Specifies the ProxyInfo data which is required in every Oracle Payments Interface request. |
null |
|
POSInfo |
Specifies the POSInfo data which is required for every Oracle Payments Interface request. |
null |
|
PartialAuthEnabled |
Specifies whether partial authorization is enabled. |
false |
|
ElectronicSignatureEnabled |
Specifies whether or not Electronic Signature processing is enabled. |
true |
|
GiftCardProcessingEnabled |
Specifies whether or not Gift Card processing is enabled. |
true |
|
PersonalCheckProcessingEnabled |
Specifies whether or not Personal Check/Cheque processing is enabled. |
true |
|
LineDisplayEnabled |
Specifies whether or not Line Item Display processing is enabled. |
false |
|
ElectronicJournal |
Specifies whether or not to add journal attributes to print lines. |
false |
|
CombinedReceipt |
Specifies whether or not to defer printing of the EFT customer receipt and instead include within the standard POS customer receipt. |
false |
|
These settings are normally correct at their default values, but can be overridden if necessary.
Table 6-2 OPI - Secondary Settings
Setting | Description | Default | Example |
---|---|---|---|
RequestResponseTimeout |
Specifies the timeout when sending / receiving messages to / from the Oracle Payments Interface in milliseconds. |
30000 |
|
ValidateMessaging |
Specifies whether or not to validate all requests / responses against their respective XSDs. |
false |
|
MaintenanceTimeout |
Specifies the timeout for the core maintenance menu in seconds. |
60 |
|
SignatureCheckTimeout |
Specifies the timeout for the Signature Check prompt when required in seconds. |
30 |
|
BusyErrorText |
Specifies the error text when the device is busy. |
Device error retry |
|
ReadResponseBuffer |
Specifies a minimum buffer amount to allocate space in memory as a rough approximation of the expected content length of an OPI Retail Response in bytes. |
1024 |
|
MaxLineItemTextLength |
Specifies the max length of an Item Description in characters. This is used to truncate the length of the item description in case the description of a product is too long during line item display on the pin entry device (PED). |
17 |
|
CombinedReceiptFilter_X |
Specifies custom filtering of information on the customer receipt. Replace X with a number between 0 and 100. A maximum of 100 filters are allowed and <blank> checks if empty lines should be suppressed. |
null |
|
IssuerId_XX |
This property maps to the OPI Card type returned as part of an OPI TransactionResponse. XX should be replaced with a a 2-character number between 00 - 45. |
IssuerId_00 = Local/Debit IssuerId_01 = VISA IssuerId_02 = MasterCard IssuerId_03 = American Express IssuerId_04 = Diners Club IssuerId_05 = JCB IssuerId_06 = CUP IssuerId_07 = SVC IssuerId_08 = Others IssuerId_09 = CUP Debit IssuerId_10 = Debit SMS IssuerId_11 = Bank Card IssuerId_12 = Discover IssuerId_13 = PayPal IssuerId_16 = UKDM/Switch IssuerId_17 = VISA Electron IssuerId_18 = VISA Debit IssuerId_19 = Maestro IssuerId_20 = VPay IssuerId_21 = Alliance IssuerId_22 = EC Chip IssuerId_23 = GiroCard IssuerId_24 = MasterCard Debit IssuerId_25 = WeChat Pay IssuerId_26 = AliPay IssuerId_31 = RESERVE-1 IssuerId_32 = RESERVE-2 IssuerId_33 = RESERVE-3 IssuerId_34 = RESERVE-4 IssuerId_35 = RESERVE-5 IssuerId_36 = RESERVE-6 IssuerId_37 = RESERVE-7 IssuerId_38 = RESERVE-8 IssuerId_39 = RESERVE-9 IssuerId_40 = RESERVE-10 IssuerId_41 = RESERVE-11 IssuerId_42 = RESERVE-12 IssuerId_43 = RESERVE-13 IssuerId_44 = RESERVE-14 IssuerId_45 = RESERVE-15 |
|
AdminMenu0.X |
Specifies the ability to customize the Admin Menu. Replace X with a value between 0 - 4. |
AdminMenu0.1 = TXT_RECONCILIATION, Reconciliation AdminMenu0.2 = TXT_CANCEL, Cancel |
|
GetCustomerVerificationAcceptLabel |
Specifies the text label of the accept button for the Get Customer Verification custom form. |
Yes |
|
GetCustomerVerificationDeclineLabel |
Specifies the text label of the decline button for the Get Customer Verification custom form. |
No |
|
DisplayMessageDuration |
Specifies the timeout duration of the display message custom form in seconds. |
30 |
|
GetPhoneNumberUseMaxLength |
Specifies whether to use max length instead of the regex for phone number capture custom form. |
true |
|
GetPhoneNumberMaxLength |
Specifies the maximum number of digits for the phone number capture custom form. |
10 |
|
GetPhoneNumberRegex |
Specifies the regular expression for the phone number capture custom form. |
\d{3}-\d{3}-\d{4} |
|
GetSSNUseMaxLength |
Specifies whether to use max length instead of the regex for social security number capture custom form. |
false |
|
GetSSNMaxLength |
Specifies the max length of the social security number capture custom form. |
9 |
GetSSNMaxLength = 9 |
GetSSNRegex |
Specifies the regular expression for the social security number capture custom form. |
\d{3}-\d{2}-\d{4} |
|
GetEmailAddressMaxLength |
Specifies the max length of the email address capture custom form. |
50 |
|
GetDriverLicenseMaxLength |
Specifies the max length of the driver license capture custom form. |
20 |
|
GetNumericFieldUseMaxLength |
Specifies whether to use max length instead of a regex for the numeric field custom form. |
true |
|
GetNumericFieldMaxLength |
Specifies the max length of the numeric field capture custom form. |
50 |
|
GetNumericFieldRegex |
Specifies the regular expression for the numeric field custom form. Default is empty. |
|
|
GetAlphanumericFieldUseMaxLength |
Specifies whether to use max length instead of a regex for the alpha numeric field custom form. |
true |
|
GetAlphaNumericFieldMaxLength |
Specifies the max length of the alpha numeric field capture custom form. |
50 |
|
GetAlphaNumericFieldRegex |
Specifies the regular expression for the alpha numeric field custom form. Default is empty. |
|
|
DisplayQRCodeButtonLabel |
Specifies the label of the button on the QR code custom form. |
Done |
|
GetPhoneNumberGuidanceText |
Specifies the guidance text when capturing a phone number. Default is empty. |
|
|
GetEmailAddressGuidanceText |
Specifies the guidance text when capturing an email address. Default is empty. |
|
|
GetSSNGuidanceText |
Specifies the guidance text when capturing a social security number. Default is empty. |
|
|
GetDateGuidanceText |
Specifies the guidance text when capturing a date of birth. Default is empty. |
|
|
GetDriverLicenseGuidanceText |
Specifies the guidance text when capturing a driver license number. Default is empty. |
|
|
GetNumericFieldGuidanceText |
Specifies the guidance text when capturing generic numeric data. Default is empty. |
|
|
GetAlphanumericFieldGuidanceText |
Specifies the guidance text when capturing generic alpha-numeric data. Default is empty. |
|
The terminal has some administration/maintenance functions. These are normally invoked from a dedicated EFT Maintenance button, but if this is not available, they could be accessed by an engineer using the EFTLink built-in test harness.
EFTLink uses DeviceProxy messages to display input prompts on the POS to manage these functions.
Below is a list of supported functionalities of the interface to OPI.
Table 6-4 OPI - Supported Functions
Function | Description |
---|---|
Payment/Payment with Loyalty |
EFTLink sends payment request to the OPI. The OPI will return a response message with formatted receipt strings for merchant and/or customer receipts. In an event of referral or communication failure where authorization cannot be obtained online then a prompt for authorization code will appear; authorization code must be obtained via telephone. After the manual authorization process is complete, a Sales Completion transaction is sent to finalize the original sale/purchase. In the event of a communication failure between EFTLink and the OPI Retail EPS, the cashier must decide whether to retry or decline the transaction. In the event of a retry; a Transaction Inquiry message is sent and if a response is returned from the OPI EPS, the response is used to finalize the sale/purchase. |
Check Payment |
EFTLink sends payment request to the OPI. The OPI will return a response message with formatted receipt strings for merchant and/or customer receipts. |
Refund |
EFTLink sends refund requests to the OPI. The OPI will refund a transaction with specified amount. |
Reversal |
EFTLink sends reversal requests to the OPI. The OPI will reverse a transaction specified by the original transaction reference. |
Sale State Notifications |
EFTLink sends line items through to the device so the customer display can be updated in line with the POS. |
Cancel Current Transaction |
EFTLink sends an abort request and if a transaction is cancellable, it is cancelled. |
Read Non-PCI Card |
EFTLink sends a card swipe request to receive data for non-pci cards. The full pan is returned in clear text, unencrypted and without tokenization. PCI cards will return a blank PAN. |
SVC Payment |
EFTLink 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 |
EFTLink sends a gift or merchandise credit card activation request to the terminal. |
SVC Add Value |
EFTLink 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 |
EFTLink sends a gift or merchandise credit card balance enquiry request to the terminal. |
SVC Unload (Cashout) |
EFTLink 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. |
SVC Reversal |
EFTLink sends a gift or merchandise credit card activate/add value/payment which is voided or post voided and the original transaction actions are reversed. |
Custom form for customer question/verification |
EFTLink 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 |
EFTLink 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 |
EFTLink 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 |
EFTLink sends a request to the terminal to capture signature. The customer signs and selects Accept. The core sends the decoded signature to the POS. |
Custom form for any alphanumeric data capture |
EFTLink sends a request to the terminal to capture any data which could be alphanumeric. A prompt is displayed regarding the type of data expected. The customer keys in the relevant data and selects submit. The core sends the data back to the POS. |
Custom form for a survey or donation selection |
EFTLink sends a request to the terminal in capture data in the form of either buttons or radio buttons. The customer can choose between a list of buttons or radio buttons which have different responses or amounts and selects submit. The core sends back the value of the button pressed back to the POS. |
Custom form for displaying a message |
EFTLink sends a request to the terminal to display a message to the customer. The message times out after a configurable amount of time. |
Custom form for displaying a scannable QR code |
EFTLink sends a request to the terminal to display a scannable QR code to the customer. The message times out after a configurable amount of time. |