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 EPS. |
localhost |
|
EPSPort |
Specifies the host port of the EPS. |
5007 |
|
DefaultOperatorId |
Specifies a default operator id for POS systems that do not provide an operator id in the CardServiceRequest. |
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. CombinedReceiptFilter_X and DoNotCombineCustomerReceiptForDecline settings become effective when this setting is true. |
false |
|
EWalletProcessingEnabled |
Specifies whether or not to enable EWallet processing. EWalletIssuerIds setting becomes effective when this setting is true. |
true |
|
InstallmentsEnabled |
Specifies whether or not to enable installment payments functionality. MaxInstallmentsAllowed, DebitCreditSelectionPromptTimeout, NoOfInstallmentsPromptTimeout, NoOfInstallmentsPromptRetries settings become effective when this setting is true. |
false |
|
CardAcquisitionEnabled |
Specifies whether to enable Card Acquisition message processing prior to Sale/Purchase message processing for 2-stage payment. |
false |
|
RefRefundUseCardTokenEnabled |
Specifies whether or not to use the Card Token to perform refund requests instead of the OriginalRRN/AcquirerTransactionReference. |
false |
|
TokenizeAnonymousCardsEnabled |
Specifies whether or not to always tokenize the card regardless of the existence of a CustomerId on the Payment CardServiceRequest. |
false |
|
QuickChipEnabled |
Specifies whether or not to enable Quick Chip functionality to allow the customer to pre-authorize their card prior to sale tendering. QuickChipAverageTransactionValue setting becomes effective when this setting is true. Warning: This setting will not be in effect unless LineDisplayEnabled is true and a value greater than 0 is set in the QuickChipAverageTransactionValue. |
false |
|
UseLegacyToke nLogicEnabled |
Specifies whether or not to use legacy token logic processing. This ensures the RRN is set on the CardServiceResponse.CardValue.Token object so that linked refunds will use the CardServiceRequest.CardValue.Token for processing as the OriginalRRN. Warning: this setting disables/disallows the ability to pay by stored card token/vault card token. |
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 seconds. |
180 |
|
DetectReceiptSignatur eString |
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 |
|
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). |
64 |
|
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. |
blank |
|
SuppressMerchantCopyForDecline |
Specifies whether or not to suppress the printing of the merchant receipt transactions are declined. |
false |
|
DoNotCombineCustomerReceiptForDecline |
Specifies whether or not to combine the customer receipt with the POS receipt when transactions are declined. |
false |
|
CardAcquisitionPromptTimeout |
Specifies the timeout for the CardInserted DeviceRequest prompt on the POS for the specified BinRange and CountryCode sent from the TransactionResponse in seconds. |
1200 |
|
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 |
|
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. |
|
|
MaxInstallmentsAllowed |
Specifies the maximum number of installments allowed per transaction. If the entered value on the installments prompt exceeds the MaxInstallmentsAllowed value, the installments prompt will retry until the configured NoOfInstallmentsPromptRetries amount is reached. |
24 |
|
NoOfInstallmentsPromptRetries |
Specifies the number of installments prompt retries. |
3 |
|
NoOfInstallmentsPromptTimeout |
Specifies the timeout in seconds of the number of installments prompt. |
600 |
|
DebitCreditSele ctionPromptTimeout |
Specifies the timeout in seconds of the prompt between Debit and Credit card type. |
600 |
|
GiftCardPinEntryOnPOSEnabled |
Specifies whether or not to enable processing of Gift Card Pins from the POS. Do not use this setting in conjunction with GiftCardPinEntryOnPEDEnabled=true as GiftCardPinEntryOnPOSEnabled will take precedence. |
false |
|
GiftCardPinEntryOnPEDEnabled |
Specifies whether or not to request a PIN for the supplied Gift Card on the PED. Do not use this setting in conjunction with GiftCardPinEntryOnPOSEnabled=true as GiftCardPinEntryOnPOSEnabled will take precedence. |
false |
|
GiftCardPinEntryTypes |
Specifies which OPI Retail Gift Card Transactions should apply Gift Card PIN processing. This is a comma-delimited string and the values must map to the OPI Retail TransType equivalents. |
27,28,29,30 |
|
GiftCardPinEntryMinimumLength |
Specifies the minimum length of the PIN to be entered on the POS. |
4 |
|
GiftCardPinEntryMaximumLength |
Specifies the maximum length of the PIN to be entered on the POS. |
4 |
|
GiftCardPinEntryRetries |
Specifies the maximum amount of retries to attempt on the POS if the default maximum length of the PIN in the OPI specification is exceeded. This property may be used in the event that the GiftCardPinEntryMinimumLength and GiftCardPinEntryMaximumLength settings are not set. |
3 |
|
GiftCardProviders |
Specifies the gift card provider to use, when a single entry is configured. If a list of providers is specified, the cashier will be prompted to select the provider from the list. If no GiftCardProvider is specified, then this entry will not be used and no value is passed to the EPS in the ProviderId element of the TransactionRequest. This is a comma-delimited string. |
blank |
|
GiftCardProvidersPromptTimeou |
Specifies the timeout in seconds to be used for the Gift Card Provider selection prompt. |
1200 |
|
EWalletIssuerIds |
Specifies which Issuer Ids to treat as EWallet Issuer Ids. EWallet processing will only function with the Issuer Ids listed as part of this property. This is a comma-delimited string and the values must map to the OPI Retail IssuerId equivalents. |
25,26 |
|
QuickChipAverageTransactionValue |
Specifies the average quickchip transaction value. This value determines the PED prompts in the transaction (for example NFC). |
20 |
|
MerchantReference |
Unique merchant reference. |
N/A |
|
MerchantReferenceFormat |
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) |
|
MerchantReferenceSpecialChar |
Specify a character that is to be passed through 'as is' in addition to the ones already mentioned. |
N/A |
|
For the merchant reference format, the following substitutions are available:
Table 6-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
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.
Below is a list of supported functionalities of the interface to OPI.
Table 6-5 OPI - Supported Functions
Function | Description |
---|---|
Payment/Payment with Loyalty |
EFTLink sends payment request to the OPI EPS. The OPI EPS 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 EPS an initial Transaction Inquiry request is sent to the OPI EPS to determine if communication is back up. If communication is still down, 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 Transaction Inquiry response is used to finalize the sale/purchase. In the event of a decline; the OPI will initially attempt to reverse the transaction, however if communication is still down, the OPI will simply fail the transaction altogether and the POS will return to the tender selection screen. |
Payment by Installments |
The POS initiates a credit/debit tender and the cashier is prompted as to whether the customer is paying by a Debit or Credit Card. If the customer is paying by Credit Card, the cashier will choose the number of installments to apply (if the customer decides to pay in installments).EFTLink receives the request from the POS and sends the payment request to the OPI EPS.The customer will proceed with the payment and this will allow the customer to be able to spread out the cost of the purchase over a number of payments. |
Payment by Card Token |
EFTLink sends a payment request to the OPI EPS with the (Stored) card token value set in the request. The OPI EPS utilizes the card token value to process the sale without customer interaction required. |
Payment by Quick Chip |
EFTLink receives a Card Acquisition request from the POS at the start of the transaction. EFTLink sends this Card Acquisition request to the OPI EPS. This allows the customer to interact with the pin entry device while the POS operator can continue to ring items through the till. When the POS tenders credit/debit at the end of the transaction; EFTLink will send a payment request with the Card Acquisition details associated with the Card Acquisition at the beginning of the transaction. The OPI EPS will process the card details in the payment request without customer interaction required. |
Check Payment |
EFTLink sends payment request to the OPI EPS. The OPI EPS will return a response message with formatted receipt strings for merchant and/or customer receipts.The Transaction Inquiry scenario outlined in the Payment/Payment with Loyalty section also applies to this transaction type. |
Refund |
EFTLink sends refund requests to the OPI EPS. The OPI EPS will refund a transaction with the specified amount.The Transaction Inquiry scenario outlined in the Payment/Payment with Loyalty section also applies to this transaction type. |
Refund with Card Token |
EFTLink sends a refund request to the OPI EPS with the (Stored) card token value set in the request. The OPI EPS utilizes the card token value to process the refund without customer interaction required. |
Reversal |
EFTLink sends reversal requests to the OPI EPS. The OPI EPS will reverse a transaction specified by the original transaction reference. The Transaction Inquiry scenario outlined in the Payment/Payment with Loyalty section also applies to this transaction type. |
Sale State Notifications |
EFTLink sends line items through to the OPI EPS so that the customer display can be updated on the terminal in line with the POS. |
Cancel Current Transaction |
POS sends an abort request to EFTLink and if a transaction is cancellable, it is cancelled. |
Read Non-PCI Card |
EFTLink sends a card swipe request to the OPI EPS 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. |
Electronic Signature capture on PED |
EFTLink sends a purchase, refund, svc payment, svc unload (cashout) or check authorization request to the OPI EPS. The signature can be captured on the pin entry device for the request provided and this signature will be confirmed by the POS operator and processed accordingly. The Transaction Inquiry scenario outlined in the Payment/Payment with Loyalty section also allows prompts for signature capture (if configured on the pin entry device). The Manual Authorization scenario outlined in the Payment/Payment with Loyalty section also allows prompts for signature capture (if configured on the pin entry device). |
SVC Payment |
EFTLink sends a gift or merchandise credit card payment request to the OPI EPS. 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. The Transaction Inquiry scenario outlined in the Payment/Payment with Loyalty section also applies to this transaction type. |
SVC Activate |
EFTLink sends a gift or merchandise credit card activation request to the OPI EPS. The Transaction Inquiry scenario outlined in the Payment/Payment with Loyalty section also applies to this transaction type. |
SVC Add Value |
EFTLink sends a gift or merchandise credit card add value request to the OPI EPS. This will only add value to an account that has been activated. The Transaction Inquiry scenario outlined in the Payment/Payment with Loyalty section also applies to this transaction type. |
SVC Balance Enquiry |
EFTLink sends a gift or merchandise credit card balance enquiry request to the OPI EPS. |
SVC Unload (Cashout) |
EFTLink sends a gift or merchandise credit card cash out request to the OPI EPS. 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. The Transaction Inquiry scenario outlined in the Payment/Payment with Loyalty section also applies to this transaction type. |
SVC Reversal |
EFTLink sends a gift or merchandise credit card activate/add value/payment to the OPI EPS which is voided or post voided and the original transaction actions are reversed. The Transaction Inquiry scenario outlined in the Payment/Payment with Loyalty section also applies to this transaction type. |
Custom form for customer question/verification |
EFTLink sends a request to the OPI EPS 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 OPI EPS 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 |
EEFTLink sends a request to the OPI EPS 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 OPI EPS 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 OPI EPS 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 OPI EPS to 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 the value of the button pressed back to the POS. |
Custom form for displaying a message |
EFTLink sends a request to the OPI EPS 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 OPI EPS to display a scannable QR code to the customer. The message times out after a configurable amount of time. |
E-Wallet payments for example, WeChat Pay and AliPay |
Flow 1 - Customer initiated transaction via E-Wallet button press on the PED. EFTLink sends a standard sale/purchase request to the OPI EPS. The customer selects the button to pay via their E-Wallet (as opposed to the usual chip and pin, swipe and other card payment methods) on the PED. The OPI EPS returns a response containing the E-Wallet data. EFTLink feeds this data back to the POS to complete the transaction. Flow 2 - Cashier initiated transaction via E-Wallet tenders on the POS. POS tenders to pay the transaction via E-Wallet tender. EFTLink sends a sale/purchase message to the OPI EPS, specifying that the PaymentMethod is E-Wallet. The OPI EPS displays a QR code which the customer scans with their E-Wallet device (typically a mobile phone). The transaction is confirmed on the OPI EPS and the WalletAuthorizationData is returned via EFTLink to the POS to complete the transaction. Flow 3 - Cashier initiated transaction via E-Wallet tenders on the POS - Customer QR code scanned on the POS. POS tenders to pay the transaction via E-Wallet tender. Cashier scans customer's E-Wallet QR code. EFTLink sends a sale/purchase message to the OPI EPS, specifying that the PaymentMethod is E-Wallet and the WalletId of the customer's E-Wallet. The transaction is confirmed on the OPI EPS and the WalletAuthorizationData is returned via EFTLink to the POS to complete the transaction. |
Two-stage payments for example, tax-free shopping |
EFTLink sends a Card Acquisition request to the OPI EPS prior to a sale/purchase request. The OPI EPS reads the customer's card details and responds with the BIN range and Country Code of the customer's card to determine (on the POS) whether this customer is eligible for tax free shopping. If so, the POS processes the tax-free refund and modifies the total transaction amount with the tax removed and sends the new amount to EFTLink. EFTLink sends a sale/purchase request with the new modified amount and the original transaction reference to the OPI EPS. The OPI EPS looks up the original card details from the transaction reference and charges the card with the modified amount to complete the transaction. |