Oracle Payment Interface (OPI)

4 Oracle Payment Interface (OPI)

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.

EFTLink General

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 OPI interface requires a minimum EFTLink version of 20.0.

System Architecture

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, additional restrictions to protocol and ciphers can be applied via dedicated configuration.

Note:

IMPORTANT

Please note that starting from version 24, strict validation of EPS device SSL certificates will be enforced using a dedicated truststore.

The OPI terminal certificate chain, with root or intermediate, should be provided by the OPI partner and imported on the EFTLink truststore; also note they may be different for production and test/stage environments.

Refer to the Oracle Retail EFTLink Framework and Configuration Installation Guide, Securing Communication to EPS Devices by Importing Trusted Xertificates section to set up the truststore with the required trusted certificates.

Also note that the core default configuration for protocols and ciphers may need changing for some OPI implementations. Please verify and eventually update the following configuration keys held within the opiretail.properties file:

truststore.ProtocolsWhiteList
truststore.CipherWhiteList
truststore.CipherBlackList

The above property keys should be updated with the device supported values by contacting the PSP vendor or by using tools to inspect the SSL connection such as:

openssl s_client -showcerts -connect <terminal ip:port>

Example of a terminal certificate details by inspecting with openssl command:

Example of the TLS protocol and cipher used by a terminal by inspecting with openssl command:

This image shows an example of TLS protocol and cipher used by a terminal by inspecting with openssl command.

Following these examples, the reported certificate or it’s root should be imported on the EFTLink truststore. The protocol TLSv1.3 should be present in the truststore.ProtocolsWhiteList and TLS_AES_256_GCM_SHA384 in the truststore.CipherWhiteList configuration keys in opiretail.properties to allow EFTLink to connect to the terminal device.

Please always contact the OPI partner for any questions about production and test terminal certificates, TLS protocols, and ciphers.

Note:

The certificates and ciphers used by OPI implementations may change over time. Please contact your OPI partner for details on how they manage this.

Fileset

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.

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= oracle.eftlink.opiretail.OPIRetailCore

Multiple Core Folder Structure Settings

The OPI Core can be configured to run multiple instances of itself. Therefore, each iteration is required to run under its own subfolder within the EFTLink installation directory. For example, C:\EFTLink\EPSCore_OPI_0 and C:\EFTLink\EPSCore_OPI_1.

This allows unique opiretail.properties files to be held and configured for each instance of the core.

EFTLink needs to be informed what the working folder names are and to achieve this, the following configuration changes are required within the EFTLinkConfig.properties file.

The property key EPSCore<n> value, can be configured to pass through parameters (comma separated) by declaring them after the cores full package name. For example: EPSCore<n> =< Full package name><space><Parameter><comma><Parameter>…)

A parameter in this case is a property key/value pair (colon separated) to specify the cores working folder. For example:

EPSCore0 = oracle.eftlink.opiretail.OPIRetailCore WorkingFolder:./ EPSCore_OPI_0

EPSCore1 = oracle.eftlink.opiretail.OPIRetailCore WorkingFolder:./ EPSCore_OPI_1

Please refer to Multiple Core Feature section within the Oracle Retail EFTLink Framework Advanced Features Guide for further information on multiple core use cases.

Configuration Settings

The full set of configuration properties is defined and commented in opiretail.properties.

Key Settings

Settings that may be different for each POS.

Table 4-1 OPI - Key Settings

Setting	Description	Default	Example
EPSAddress	Specifies the host address of the EPS.	localhost	`EPSAddress = IP ADDRESS`
EPSPort	Specifies the host port of the EPS.	5007	`EPSPort = 5007`
EPSName	Specifies the name of the EPS. This is typically used to identify the PaymentProviderName during Tax Free processing.	Blank	`EPSName = [PaymentProviderName]` where the PaymentProviderName is any supported provider.
truststore.trustAllServers	Disable validation of certificates with the truststore on connection between EFTLink and OPI devices. Please note, disabling validation of the trusted certificate is never a recommended practice. Ciphers and protocols will still continue to be restricted as configured below.	false	truststore.trustAllServers = false Disabling validation of the truststore is never a recommended practice.
truststore.ProtocolsWhiteList	Restricts the protocols which are permissible in the connection between EFTLink and EPS devices. Default allows for TLS 1.3 or 1.2 security.	TLSv1.3,TLSv1.2	truststore.ProtocolsWhiteList = TLSv1.3,TLSv1.2
truststore.CipherWhiteList	Restricts the ciphers which are permissible in the connection between EFTLink and EPS devices. The whitelist only includes ciphers which are approved under Oracle Approved Technologies: Security Protocols	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_AES_128_GCM_SHA256, TLS_AES_128_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, TLS_AES_128_CCM_SHA256, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_CCM, TLS_ECDHE_ECDSA_WITH_AES_128_CCM	truststore.CipherWhiteList = `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,` `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,` `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,` `TLS_AES_128_GCM_SHA256,` `TLS_AES_256_GCM_SHA384,` `TLS_CHACHA20_POLY1305_SHA256,` `TLS_AES_128_CCM_SHA256,` `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,` `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,` `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,` `TLS_ECDHE_ECDSA_WITH_AES_256_CCM,` `TLS_ECDHE_ECDSA_WITH_AES_128_CCM`
truststore.CipherBlackList	Restricts the ciphers which are not permissible in the connection between EFTLink and EPS devices. The blacklist only includes ciphers which are not approved under Oracle Approved Technologies: Security Protocols	SSL_., TLS_EMPTY_., ._SHA, ._3DES_., ._DES_., ._WITH_NULL_., ._anon_., .EXPORT., .LOW., .MD5., .DES., .RC2., .RC4., .PSK., TLS_DH_., TLS_DHE_.*	truststore.CipherBlackList = `SSL_.,` `TLS_EMPTY_.,` `._SHA,` `._3DES_.,` `._DES_.,` `._WITH_NULL_.,` `._anon_.,` `.EXPORT.,` `.LOW.,` `.MD5.,` `.DES.,` `.RC2.,` `.RC4.,` `.PSK.,` `TLS_DH_.,` `TLS_DHE_.*`
DefaultOperatorId	Specifies a default operator id for POS systems that do not provide an operator id in the CardServiceRequest.	EFTLink OPI Operator	`DefaultOperatorId = EFTLink OPI Operator`
DefaultBaseCurrency	Specifies the default base currency to be used as part of the TransCurrency element in the OPI Retail messages.	GBP	`DefaultBaseCurrency = GBP`
DefaultCheckType	Specifies the default check type for check processing.	01	`DefaultCheckType = 01`
DefaultCheckName	Specifies the default check name for check processing.	Personal Check	`DefaultCheckName = Personal Check`
SiteId	Specifies the SiteId data which is required in every Oracle Payments Interface request.	null	`SiteId = Site`
ProxyInfo	Override the ProxyInfo value reported on every Oracle Payments Interface request.	null	`ProxyInfo = OPI Version 24.0`
POSInfo	Specifies the POSInfo data which is required for every Oracle Payments Interface request.	null	`POSInfo = Test POS`
PartialAuthEnabled	Specifies whether partial authorization is enabled.	false	`PartialAuthEnabled = true`
ElectronicSignatureEnabled	Specifies whether Electronic Signature processing is enabled.	true	`ElectronicSignatureEnabled = true`
GiftCardProcessingEnabled	Specifies whether Gift Card processing is enabled.	true	`GiftCardProcessingEnabled = true`
PersonalCheckProcessingEnabled	Specifies whether Personal Check/Cheque processing is enabled.	true	`PersonalCheckProcessingEnabled = true`
LineDisplayEnabled	Specifies whether Line Item Display processing is enabled.	false	`LineDisplayEnabled = true`
ElectronicJournal	Specifies whether to add journal attributes to print lines.	false	`ElectronicJournal = true`
CombinedReceipt	Specifies whether 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	`CombinedReceipt = true`
EWalletProcessingEnabled	Specifies whether to enable EWallet processing. EWalletIssuerIds setting becomes effective when this setting is true.	true	`EWalletProcessingEnabled = true`
InstallmentsEnabled	Specifies whether to enable installment payments functionality. MaxInstallmentsAllowed, DebitCreditSelectionPromptTimeout, NoOfInstallmentsPromptTimeout, NoOfInstallmentsPromptRetries settings become effective when this setting is true.	false	`InstallmentsEnabled = true`
LoyaltyBrandsEnable	Specifies whether to enable Loyalty Brands.	false	`LoyaltyBrandsEnabled = true`
AllowedLoyaltyBrands	A comma-separated list of allowed loyalty brands. Dependent on property LoyaltyBrandsEnabled.		`AllowedLoyaltyBrands = AppleVas,Google Smarttap`
CardAcquisitionEnabled	Specifies whether to enable Card Acquisition message processing prior to Sale/Purchase message processing for 2-stage payment.	false	`CardAcquisitionEnabled = true`
RefRefundUseCardTokenEnabled	Specifies whether to use the Card Token to perform refund requests instead of the OriginalRRN/AcquirerTransactionReference.	false	`RefRefundUseCardTokenEnabled = false`
TokenizeAnonymousCardsEnabled	Specifies whether to always tokenize the card regardless of the existence of a CustomerId on the Payment CardServiceRequest.	false	`TokenizeAnonymousCardsEnabled = true`
QuickChipEnabled	Specifies whether 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	`QuickChipEnabled = false`
UseLegacyToke nLogicEnabled	Specifies whether 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	`UseLegacyTokenLogicEnabled = true`
PayByLinkExpiresAtHours	Defines how many hours a generated URL should be considered valid.	24	`PayByLinkExpiresAtHours = 24`
LegacyXstoreCopyCardTokenToOrigAltTransRef	Enable when using Xstore pre V19.0.1 and Cardless Reference Refund required when moving from POS Jni Core to OPI Core. When process a Referenced Refund, it will copy CSRequest.Card.Token to OPI Refund Request OrigAltTransRef if CSRequest.TransactionReference is not set.	false	`LegacyXstoreCopyCardTokenToOrigAltTransRef = true`
CustomFormsUseSeparateTextLines	Define whether the core will move the separate TextLines in the DeviceRequest from PromptText to PromptText2, PromptText3, PromptText4 & PromptText5 Note, when obtaining Signature, these additional fields will be Title2, Title3, Title4 & Title5	false	`CustomFormsUseSeparateTextLines = true`
TerminalMessagesEnabled	Define whether the core will connect to PED to receives terminale messages. PSP terminal should support this functionality.	False	`TerminalMessagesEnabled=false`
TerminalMessagesEndpoint	When enabled, PED wss endpoint used to receive terminal message. PSP vendor should provide the address.	Empty	`TerminalMessagesEndpoint=wss://<terminal_ip:port>/path`
TerminalMessagesConnectionTimeoutMillis	When enabled, connection timeout in milliseconds to TerminalMessagesEndpoint.	3000	`TerminalMessagesConnectionTimeoutMillis=3000`
EPSTerminalID	Specify the unique name for EPS Terminal Id.	Empty	`EPSTerminalID = EPS1`
EnableSettingOfTerminalId	Whether to use the EPS terminal Id.	False	`EnableSettingOfTerminalId = false`

Secondary Settings

These settings are normally correct at their default values but can be overridden if necessary.

Table 4-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	`RequestResponseTimeout = 200`
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	`DetectReceiptSignatur eString = # Signature #`
ValidateMessaging	Specifies whether to validate all requests / responses against their respective XSDs.	false	`ValidateMessaging = true`
MaintenanceTimeout	Specifies the timeout for the core maintenance menu in seconds.	60	`MaintenanceTimeout = 30`
SignatureCheckTimeout	Specifies the timeout for the Signature Check prompt when required in seconds.	30	`SignatureCheckTimeout = 15`
BusyErrorText	Specifies the error text when the device is busy.	Device error retry	`BusyErrorText = Busy Device Error`
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	`ReadResponseBuffer = 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) and on S/P request payload.	64	`MaxLineItemTextLength = 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	`CombinedReceiptFilter_0 = <blank>`
SuppressMerchantCopyForDecline	Specifies whether to suppress the printing of the merchant receipt transactions are declined.	false	`SuppressMerchantCopyForDecline = false`
DoNotCombineCustomerReceiptForDecline	Specifies whether to combine the customer receipt with the POS receipt when transactions are declined.	false	`DoNotCombineCustomerReceiptForDecline = 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	`CardAcquisitionPromptTimeout = 1200`
GetCustomerVerificationAcceptLabel	Specifies the text label of the accept button for the Get Customer Verification custom form.	Yes	`GetCustomerVerificationAcceptLabel = No`
GetCustomerVerificationDeclineLabel	Specifies the text label of the decline button for the Get Customer Verification custom form.	No	`GetCustomerVerificationDeclineLabel = No`
DisplayMessageDuration	Specifies the timeout duration of the display message custom form in seconds.	30	`DisplayMessageDuration = 60`
GetPhoneNumberUseMaxLength	Specifies whether to use max length instead of the regex for phone number capture custom form.	true	`GetPhoneNumberUseMaxLength = true`
GetPhoneNumberMaxLength	Specifies the maximum number of digits for the phone number capture custom form.	10	`GetPhoneNumberMaxLength = 12`
GetPhoneNumberRegex	Specifies the regular expression for the phone number capture custom form.	\d{3}-\d{3}-\d{4}	`GetPhoneNumberRegex = \d{3}-\d{3}-\d{4}`
GetPhoneUseType63	Whether to use the transaction type 63 GetAlphaNumeric instead of the GetNumericField for capture Phone from PED.	false	`GetPhoneUseType63 = false`
GetSSNUseMaxLength	Specifies whether to use max length instead of the regex for social security number capture custom form.	false	`GetSSNUseMaxLength = true`
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}	`GetSSNRegex = \d{3}-\d{2}-\d{4}`
GetEmailAddressMaxLength	Specifies the max length of the email address capture custom form.	50	`GetEmailAddressMaxLength = 100`
GetDriverLicenseMaxLength	Specifies the max length of the driver license capture custom form.	20	`GetDriverLicenseMaxLength = 20`
GetNumericFieldUseMaxLength	Specifies whether to use max length instead of a regex for the numeric field custom form.	true	`GetNumericFieldUseMaxLength = true`
GetNumericFieldMaxLength	Specifies the max length of the numeric field capture custom form.	50	`GetNumericFieldMaxLength = 50`
GetNumericFieldRegex	Specifies the regular expression for the numeric field custom form. Default is empty.		`GetNumericFieldRegex = \d{3}-\d{2}-\d{4}`
GetAlphanumericFieldUseMaxLength	Specifies whether to use max length instead of a regex for the alpha numeric field custom form.	true	`GetAlphanumericFieldUseMaxLength= true`
GetAlphaNumericFieldMaxLength	Specifies the max length of the alpha numeric field capture custom form.	50	`GetAlphaNumericFieldMaxLength = 50`
GetAlphaNumericFieldRegex	Specifies the regular expression for the alpha numeric field custom form. Default is empty.		`GetAlphaNumericFieldRegex = \d{3}-\d{2}-\d{4}`
DisplayQRCodeButtonLabel	Specifies the label of the button on the QR code custom form.	Done	`DisplayQRCodeButtonLabel = Cancel`
GetPhoneNumberGuidanceText	Specifies the guidance text when capturing a phone number. Default is empty.		`GetPhoneNumberGuidanceText = Please input your phone number below in the form of XXX-XXX-XXXX (replace X with a number between 0-9)`
GetEmailAddressGuidanceText	Specifies the guidance text when capturing an email address. Default is empty.		`GetEmailAddressGuidanceText = Please input your email address below, for example; test@oracleretail.com.`
GetSSNGuidanceText	Specifies the guidance text when capturing a social security number. Default is empty.		`GetSSNGuidanceText = Please input your social security number below, for example; 078-05-1120`
GetDateGuidanceText	Specifies the guidance text when capturing a date of birth. Default is empty.		`GetDateGuidanceText = Please input your date of birth below, for example; 1971-01-01 (YYYY-MM-DD)`
GetDriverLicenseGuidanceText	Specifies the guidance text when capturing a driver license number. Default is empty.		`GetDriverLicenseGuidanceText = Please input your driving license below, for example; 123 456 789`
GetNumericFieldGuidanceText	Specifies the guidance text when capturing generic numeric data. Default is empty.		`GetNumericFieldGuidanceText = Please input your loyalty number below, for example; 123-456-7891`
GetAlphanumericFieldGuidanceText	Specifies the guidance text when capturing generic alpha-numeric data. Default is empty.		`GetAlphanumericFieldGuidanceText = Please enter your name below incl. middle names, for example; Joe M Bloggs`
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	`MaxInstallmentsAllowed = 30`
NoOfInstallmentsPromptRetries	Specifies the number of installments prompt retries.	3	`NoOfInstallmentsPromptRetries = 1`
NoOfInstallmentsPromptTimeout	Specifies the timeout in seconds of the number of installments prompt.	600	`NoOfInstallmentsPromptTimeout = 60`
DebitCreditSele ctionPromptTimeout	Specifies the timeout in seconds of the prompt between Debit and Credit card type.	600	`DebitCreditSelec tionPromptTimeout = 60`
GiftCardPinEntryOnPOSEnabled	Specifies whether 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	`GiftCardPinEntryOnPOSEnabled = true`
GiftCardPinEntryOnPEDEnabled	Specifies whether 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	`GiftCardPinEntryOnPEDEnabled = true`
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	`GiftCardPinEntryTypes = 27,28,29,30`
GiftCardPinEntryMinimumLength	Specifies the minimum length of the PIN to be entered on the POS.	4	`GiftCardPinEntryMinimumLength = 3`
GiftCardPinEntryMaximumLength	Specifies the maximum length of the PIN to be entered on the POS.	4	`GiftCardPinEntryMaximumLength = 6`
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	`GiftCardPinEntryRetries = 5`
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	`GiftCardProviders = SVS, GIVEX`
GiftCardProvidersPromptTimeou	Specifies the timeout in seconds to be used for the Gift Card Provider selection prompt.	1200	`GiftCardProvidersPromptTimeout==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.	13,25,26,31,32,33,34,35,36,37,38,39,60	`EWalletIssuerIds = 13,25,26,31,32,33,34,35,36,37,38,39,60`
EnforceCardNameSetByOPI	If true, the card name returned in the CardServiceResponse adheres to the mappings specified by the OPI spec and is not overridden by any mapping performed within the cardrange.xml.	false	`EnforceCardNameSetByOPI = true`
QuickChipAverageTransactionValue	Specifies the average quickchip transaction value. This value determines the PED prompts in the transaction (for example NFC).	20	`QuickChipAverageTransactionValue = 20`
InvoicePaymentPromptForCardOrCashEnabled	Specifies whether to prompt for Card or Cash at the POS for Invoice Payment transactions.	false	`InvoicePaymentPromptForCardOrCashEnabled`
InvoicePaymentPromptForCardOrCashTimeout	Specifies the timeout in seconds of the prompt for Card or Cash for Invoice Payments transactions.	600	`InvoicePaymentPromptForCardOrCashTimeout = 720`
InvoicePaymentPromptScanBarcodeRetries	Specifies the number of Scan Barcode prompt retries.	3	`InvoicePaymentPromptScanBarcodeRetries = 6`
CellPhoneRechargePromptForCardOrCashEnabled	Specifies whether to prompt for Card or Cash at the POS for Cell Phone Recharge transactions.	false	`CellPhoneRechargePromptForCardOrCashEnabled = true`
CellPhoneRechargePromptForCardOrCashTimeout	Specifies the timeout in seconds of the prompt for Card or Cash for Cell Phone Recharge transactions.	600	`CellPhoneRechargePromptForCardOrCashTimeout = 720`
MerchantReference	Unique merchant reference.	N/A	`MerchantReference=Merchant A`
MerchantReferenceFormat	Specify the format of the merchant reference - replaces static value with a dynamically generated value using several substitutions. See Merchant Reference Formats.	R (use existing static merchant ref)	`MerchantReferenceFormat=R-dddddddddd-SSSSSS.WW WWWW.YYYYMMDD.hhmmss.TTTTTT.qq`
CapCancellation	Determines response for the getCapCancellation request.	true	`CapCancellation = false`
CapReversal	Determines response for the getCapReversal request	true	`CapReversal = false`
MerchantReferenceSpecialChar	Specify a character that is to be passed through 'as is' in addition to the ones already mentioned.	N/A	`MerchantReferenceSpecialChar = K`
PrintDataLogMasking	When enabled force masking on log of receipt information on <PrintData> tag	false	`PrintDataLogMasking = false`
AlternativePrintDataOrder	If true, then the OPICore expects the customer receipt copy first and the merchant receipt copy second inside the PrintData field within the transaction response.	false	`AlternativePrintDataOrder = true`

Merchant Reference Formats

For the merchant reference format, the following substitutions are available:

Table 4-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

Administration Functions

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.

Table 4-4 OPI - Administration Functions

Function	Description
Day End	Print an end day report and close the current day. Manual alternative to automated ReconciliationWithClosure.

Supported Functions

Below is a list of supported functionalities of the interface to OPI.

Table 4-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	EFTLink 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.
Invoice payments	The POS adds a non-merch item “Invoice Payment” which initiates an Invoice Payment transaction. The cashier is prompted as to whether the customer would like to pay by “Cash” or “Card” (If configured). The cashier is further prompted to “Please scan the invoice barcode”. The cashier may key or scan the invoice barcode. EFTLink receives the request from the POS and sends the “Invoice Payment” request to the OPI EPS. The customer will proceed with the payment at this point. If the customer selected to pay by “Cash” during the initial prompt on the POS, the OPI EPS will simply clear the invoice as paid and send back the successful response. The following prompts are skippable: 1. The customer will input on the PED the amount of the invoice they would like to pay in whichever currency the PED is configured. If the customer selected to pay by “Card” during the initial prompt on the POS, the PED will prompt as to whether or not the customer would like to pay by “Cash”, “Credit” or “Debit”. The customer may choose how to pay at this point. If the customer selects “Cash”, the invoice will be cleared as paid. If the customer selects “Credit” or “Debit” card, the usual steps will take place for a typical Card transaction. Invoice payments are not reversible at this time. However, if a card payment was made, the cashier may choose to reverse as a standard card payment. It is assumed that the merchant will have the necessary measures in place to avoid issues with “Cash” payments (in terms of a customer not having enough cash to pay for the transaction and so on). The Transaction Inquiry scenario outlined in the Payment/Payment with Loyalty section also applies to this transaction type. .
Cell phone recharge (Top-up)	The POS adds a non-merch item “Cell Phone Recharge” which initiates a Cell Phone Recharge transaction. The cashier is prompted as to whether the customer would like to pay by “Cash” or “Card” (If configured). EFTLink receives the request from the POS and sends the “Cell Phone Recharge” request to the OPI EPS. The customer will proceed with the payment at this point. If the customer selected to pay by “Cash” during the initial prompt on the POS, the OPI EPS will simply clear the invoice as paid and send back the successful response. The following prompts are skippable: 1. The customer will be prompted by the PED to select which Service Provider they are with. 2. The customer will be prompted to select a RechargeAmount which they would like to recharge (top-up) their phone by. 3. The customer will be prompted by the PED to input their phone number. If the customer selected to pay by “Card” during the initial prompt on the POS, the PED will prompt as to whether the customer would like to pay by “Cash”, “Credit” or “Debit”. The customer may choose how to pay at this point. If the customer selects “Cash”, the invoice will be cleared as paid. If the customer selects “Credit” or “Debit” card, the usual steps will take place for a typical Card transaction. Cell phone recharge payments are not reversible. However, if a card payment was made, the cashier may choose to reverse as a standard card payment. It is assumed that the merchant will have the necessary measures in place to avoid issues with “Cash” payments (in terms of a customer not having enough cash to pay for the transaction and so on). The Transaction Inquiry scenario outlined in the Payment/Payment with Loyalty section also applies to this transaction type.
PLCC (Private Label Credit Cards)	Support for PLCC has been added to the OPI core. PLCC Account Lookup – this is used to look up the account details for a PLCC. This includes the credit balance and remaining credit, and the card token in addition to cardholder information. This can be used to check the balance of the card prior to performing an account payment or tender transaction. The PLCC can be presented to the PED. If the PLCC token is saved against the customer, the saved card token can be used in CNP scenarios. PLCC Payment On Account – this transaction type can be used to make a payment against the balance on the PLCC. The payment transaction can be initiated by the POS and can usually include most types of tender except Credit cards. Some tenders such as Debit cards would be processed by the PED. This would usually be proceeded by an Account Lookup to determine the outstanding balance. PLCC Application Request – this is used to perform a new PLCC application request. Some of the required detail is collected on the POS and sent to EFTLink within the request message, but the PED may also collect some data directly from the applicant. Note that PLCC application process and data is very dependent on the PSP and the finance company offering the PLCC, and may require custom extensions on the POS. Tender by PLCC – In order to allow the POS to tender explicitly by PLCC, a new eWallet Payment Method “61” “PLCC” has been added, which the POS can set on the Sale/Purchase request message, instructing the PED to only allow tender by PLCC. Tender by Debit card – Since PLCC Payment On Account cannot be tendered by credit card, a new eWallet PaymentMethod “62” “Debit Card” has been added, allowing the POS to instruct the PED to only allow tender by Debit Card.
Card Acquisition	Support for card acquisition has been added to the OPI core. The OPI core will now accept an explicit card acquisition request from the POS. the customer will be prompted to present their payment card to the PED so the details of their card (tokens) can be pre-read. This can be useful in several scenarios such as looking up the sales transactions that used that same card, when shopper requests to return items, but does not have the original receipt, thus allowing for a referenced refund, rather than an un-referenced (blind) refund. The following fields are returned to the POS (as determined by PSP) none of which are in scope of PCI DSS - CardAlias, CustomerId, CardHolderEmail, CardToken.
Pre-authorization transactions	Support for card pre-authorization transactions has been added to the OPI core. Authorization Transaction – this message type can be used to request an authorization for funds (without capture/settlement). This can be used for gaining authorization for POS transactions that are not being immediately picked up or delivered to a customer, such as pre-sales and so on, and can be for either payment cards presented to the PED, or with a saved Card Token. The POS can then request completion (capture) of the authorization when the goods are picked up or dispatched, using the Sales Completion transaction. Authorization Release Transaction – this message can be used to release or cancel an existing authorization. Top-UpAuthorization Transaction – this message can be used to increase the amount of an existing authorization. It is possible that multiple authorizations are performed during the lifecycle of a POS transaction or order.
PED Status Messages	Support for PED status messages have been added to the OPI core. The OPI core has configurations that can be enabled, that will instruct EFTLink to connect to an endpoint running on the OPI implementation to establish a websocket channel, and will be listening on this websocket, for Terminal Status messages during the TransactionRequest operation. This is a “fire and forget” message sent from the PED to the POS, and there is no response message. These messages would usually be the same/similar as those messages that are displayed on the PED to instruct/inform the shopper, for example to remove their card.
PSP Cloud Host Endpoint	Support for a cloud host endpoint has been added to the OPI core. This allows a PSP to offer their OPI implementation in the cloud, rather than locally, on-premises. In order to enable this all Retail OPI request messages have a new field, RequestTerminalId, which allows the PSP OPI implementation to route the transaction to the appropriate PED.