3 Secure Development
Core-Host API
A standard API is available to payment systems in the EFTLink framework.
Scope
The EFTLink framework presents a standard (Java API) interface for "plugin" payment system implementations, referred to as "cores". It is within the core that all business logic and communications processing that is required by that payment system is implemented. The framework provides an execution environment and access to POS resources such as operator screen/keyboard and printer. It is a best practice to have all Oracle Retail EFTLink support requests submitted through a single point of contact for that customer environment; the client designated administrator is usually designated to perform this role.
Figure 3-1 EFTLink OPI Server/Router
Message Flow
The EFTLink Core API is a set of Java classes, but it is essential when developing a new core to also understand the underlying XML socket protocol that is encapsulated in those classes, to keep in mind how each method call affects the channel/socket connections and to be aware of the generally multi-threaded nature of the architecture.
The diagram below describes the flow of messages from the client application through EFTLink to a payment core.
Figure 3-2 Message Flow
Channel 0
Channel 0 payment/admin request from the POS will be presented to the core as method calls (for example, authorise()). This is a blocking call in that the channel 0 response will not be sent to the POS until that method returns.
Channel 1
Channel 1 device proxy requests are triggered by the core calling a display/print method on the EFTLink framework host. This is a blocking call in that the method will not return until the relevant display/print process has completed on the POS or timed out.
Channel/Socket Contention
There can only be one active request per channel at any one time. Any attempt to use a channel that is already in use is taken as an implicit cancellation of the in-progress session. However, this rule is implemented differently on channel 0 and 1. On channel 0 (POs to EFTLink), the new request (typically a payment request) is rejected as "busy" and the active session is left to run to completion. On channel 1 (EPS to EFTLink), the old session is aborted, and the new request (typically a display request) is processed as the new active session.
Socket/XML Message Abstraction
The Core-Host API abstracts the socket handling and XML message content into a set of java classes and interfaces. Socket/channel activity is passed to the core as an event (for example, the authorise() method call). Message content is abstracted into entity classes. For example, EPSRequest/EPSCard and passed as arguments to those events. All the properties in the entity classes will have a directly related XML element or attribute, and vice versa.
The XML protocol specification should be used as the primary point of reference for how and when a particular property is used.
EPSCore/EPSHost
The key Interfaces that a core has to use are EPSCore and EPSHost. The core implements EPSCore and so receives events (for example authorization requests) from the EFTLink framework. The EFTLink framework implements EPSHost to allow the core to access framework resources and to interact with the POS.
The current version of EPSCore is EPSCore_1_3. Earlier versions are still supported for backward compatibility, but any new core should implement the highest available version to benefit from any recent enhancements.
EPSCore Event Mapping
The following table shows the mapping between the XML message and the API method.
Table 3-1 EPSCore Event Mapping
| XML Message | API Method |
|---|---|
|
ServiceRequest of type Logon |
logon |
|
ServiceRequest of type Logoff |
logoff |
|
ServiceRequest of type Reconciliation |
reconciliation |
|
ServiceRequest of type Administration |
maintenance |
|
CardServiceRequest of any type (such as CardPayment) |
authorise |
|
SaleStateNotification of any Type (SaleStart, SaleEnd) |
posTransactionInProgress |
|
any message of type AbortRequest |
abort |
EPSHost Action Mapping
The following table shows the mapping between the API method and the XML message.
Table 3-2 EPSHost Action Mapping
| API Method | XML Message |
|---|---|
|
display |
DeviceRequest of type Output to CashierDisplay device (simple text display to operator) |
|
|
DeviceRequest of type Output to Printer device (simple print of preformatted text) |
|
deviceAccess |
DeviceRequest of any type with extended attributes - timeout and so on. |
EPSRequest/EPSResult Classes
The key entity classes that a core must use are EPSRequest and EPSResult. Most EPSCore events carry with them an EPSRequest data object. This holds all the details extracted from the POS XML message. On completing the requested action, the core builds an EPSResult object to return to the host to show the success/fail status of the operation along with all related data (for example payment card details).
DeviceRequest/DeviceResponse Classes
As part of processing the POS request, the core is likely to need to display and/or print messages at the POS. This is done by creating a DeviceRequest object specifying the type of display required and invoking the deviceAccess() method on the host interface. The host will build a DeviceResponse object to return to the core to show the success/fail status of the operation along with all related data (for example keyed data entered by the operator).
Mandatory Content
The core only needs to implement as much of the specified functionality as is required to fulfil the requirements of the payment system. However, where the protocol defines mandatory fields that are not covered by this approach, the core must populate those fields with suitable default values.
Development Considerations
A number of functions must be taken into consideration when developing cores to ensure a base set of functionalities is available.
Logging
EFTLink uses log4j and maintains a daily log file eftlink_mmdd.log. Core implementers are encouraged to integrate their logging into this system. For debug purposes, EFTLink also has a feature where all logging is also echoed to a pop-up dialog box. To support this, individual class logging should be initializsed by calling getLogger() from the EPSLogger class for example.
private Logger log = EPSLogger.getLogger(OPICardServiceSession.class);
Multi-threading and Synchronisation
The system architecture is inherently multi-threaded. Each new call from the framework will be in a new thread and the communications implementation to the terminal/EPS is likely to introduce further threads. Care must be taken to ensure these threads are synchronized and that data is suitably protected.
Progress Messages
Ideally, the core should send regular progress display messages to the POS to keep the operator informed on the state of the transaction.
Most payment systems report their ongoing status, either by explicit display messages or some form of status broadcast, but where there is no such status update, the core should still endeavour to report progress as far as is possible.
Printer Management
The default way of handling printout is to send it directly to the POS as a device proxy request. However, it is also possible to buffer printout in the core and then include that text in the authorization response, to allow the POS to merge the EFT voucher into the standard POS receipt to save paper. Not all POS systems support this feature, so it should always be made configurable.
It is also possible to tag print lines as being "journal" so that they can be stored rather than printed. Again, not all POS systems support this feature.
Administration Functions
It is quite common for a payment system to have some maintenance/engineer functions that need to be executed when installing the terminal or on a regular basis. Such operations can be put on a maintenance menu, defined as series of device proxy display requests. The POS invokes this menu via an EFT Maintenance option that has no business logic associated with it, but just triggers an "Administration" service request and opens channel 1 for device proxy access.
Cancellation
The POS may have a "cancel" button which can be pressed to try to abort a transaction that has been started unintentionally or that is taking too long. This is done by the POS sending an AbortRequest, which in turn is passed to the core as abort(). This should be interpreted as a request not a command - if it is possible to cleanly close the active transaction, then this should be done, but if not, the request ban be ignored.
Translation
Textual display and print data received from the payment system should be shown as is. However ancillary display messages should be shown in the correct language for the region. EFTLink has a "Text" translation class, and a set of LangXX.properties country-specify lookup files.
EFTLink Server Compatibility
When deployed in Server mode, there will be multiple instances of the EFTLink main application class (OPIServer) and multiple instances of the core class, all in memory at the same time. Each instance runs from its own set of configuration files in a sub-folder under the main EFTLink folder.
This imposes rules/restrictions on the core:
-
No hard-coded file paths. Always access files relative to INSTANCE_ROOT() or DATA(). Only use PRIMARY_ROOT for files that are intentionally the same for all instances.
Note:
When using framework file access helper classes such as EPSFileProperties, EPSSecureFile and so on, the use of INSTANCE_ROOT() is automatically applied by the framework.
-
Do not store instance-specific data in static storage. Static storage will in effect be shared between all instances.
-
No passing files (for example signature images) by name. The POS will be on a remote system.
Core How-Tos
Additional information regarding the core:
MiscellaneousData
MiscellaneousData is a free-format text property, available in both the EPSRequest and EPSResult classes, which can be used for any data that is not covered by the standard property options. It can be accessed as a String in the normal way, but there is also an option to reference it as MiscellaneousDataProperties to access it as a collection of key-value pairs but note that the underlying storage is still the same MiscellaneousData String.
Miscellaneous Data Disclaimer
EFTLink along with some selected Cores, has the ability for additional
data to be sent and received in a field called <MiscellaneousData>.
This can be used by System Implementers (SIs) and Payment Service Providers (PSPs) to pass additional data in the messages between Xstore and the Payment Providers, using custom code.
Typically, this is used to add directives which we can trigger different payment workflows however it can also be used to capture additional payment data for downstream processing for the Retailer's to use for reconciliation or financial purposes.
Under no circumstances should any PCI or potentially sensitive PII data be placed in this field. Oracle will not be responsible for any issues caused by integration changes made by SIs, Retailers and Payment Providers, that enable sensitive data to be added into this field.
Session Properties
If the POS has included data in the XML to EFTLink that for some reason is not mapped into the existing API objects, there is still a means of drilling down into the Session for more detail. The EPSHost Interface includes a getSession() method returning an EPSSession object. This is primarily there to allow access to session variables when processing methods that do not use EPSRequest, such as logon() or maintenance(), but the EPSSession Interface reference can also be cast back to the appropriate underlying OPIXxxSession object to get access to the relevant session properties and even to the XML Document objects.
Secure Data
EFTLink Framework provides three security features to protect data used by the core.
By using these features rather than any bespoke implementation in the core, the security system is made more future-proof because changes (for example encryption enhancements) need only be applied in the framework.
Note:
Sensitive text data should not be stored in Java Strings. Better to use a character array so that the memory can then be explicitly cleared after use.
Restricted Access
The framework provides a DATA() folder with restricted user access rights. Any files created in that folder will only be accessible by the EFTLink host account.
Key Storage
The EPSKeyStoreManager class can be used to store encryption keys (or in fact any text-based data). The data will be encrypted and stored in a password-protected Java Keystore, transparent to the core.
Encrypted File Storage
The EPSSecureFile class can be used to store data in an encrypted file. The read/write interface presented by EPSSecureFile is based on streams, to avoid restricting it to any specific data type. Any data that can be expressed as a stream can be encrypted and serialized in this way. One way of doing this is to define a new serializable entity class to hold all the relevant sensitive data and interface with EPSSecureFile using ObjectInputStream and ObjectOutputStream.
Examples of each of these are included in the EPSSimulator core class.
Further information is available at the following location:
https://confluence.oraclecorp.com/confluence/display/EF/OPIClient-based+Cores