Retail:EDPS ECR Greece integration - Configuration and User Guide
Contents |
Introduction
This document describes the installation and configuration of the EDPS ECR Greece integration for Openbravo. EDPS ECR Greece is the payment platform created by EDPS for Greece.
This integration is based on the Openbravo Country Compliance Plugins architecture that aims to completely isolate Openbravo from different integration implementations. For the EDPS ECR Greece integration, this development implements the Payment events API for Web POS.
The Payment events API for Web POS is configured in Openbravo just by setting the URL of the endpoint of the integration that implements the API.
Payment providers
The EDPS ECR Greece integration is based on the Event Payment Provider functionality provided by Openbravo that provides a common platform for payments events. It makes use of the Event Payment Provider that must be used when configuring the Provider Group. The Guide to configure and use the payment methods functionality in Openbravo can be found here: http://wiki.openbravo.com/wiki/Retail:Payment_Methods_grouping_by_Provider_User_Guide
Payment events configuration
Every touchpoint is linked to a payment event that must be configured in order to link all the required fields needed to process payments. This event is configured in the window Event Subscriptions:
- Public Event: For payments the value must be Event Payment Provider.
In the Touchpoint integration system tab is configured the endpoint details:
- Touchpoint: Touchpoint that is connected to this payment event. It is the touchpoint application that invokes the URL to execute the payment integration..
- URL: Endpoint address for the payment integration implementation.
The EDPS ECR Greece integration is implemented by the Openbravo hardware manager and the URL has the following format:
- Protocol: http:// or https://.
- Host: The host where the hardware manager is located. Usually localhost.
- Port: The port where the hardware manager is listening. Usually 8090 for http:// and 8190 for https://.
- Path: process/EDPSECR
- Query string parameters:
- mode: Value can be serial or mock. By default serial. Mode mock simulates a payment terminal connected for development and testing purposes. IT MUST NOT BE USED IN PRODUCTION ENVIRONMENTS.
- serialport: The serial port of the computer the payment terminal is connected to. Usually COM1: for Windows systems and /dev/ttyUSB0 for Linux systems
- timeout: The time in milliseconds the hardware manager waits before canceling a payment request. By default 300000, 5 minutes.
- timeoutack:' The time in milliseconds the hardware manager waits before receiving an acknowledged response from the terminal. By default 500, 0,5 seconds.
An example of a valid URL value is:
http://localhost:8090/process/EDPSECR?serialport=/dev/ttyUSB0&timeout=300000&acktimeout=1000
Hardware manager installation and configuration
The Hardware Manager is a native java application that is responsible for managing all the POS hardware required like receipt printers, cash drawers, customer displays, … In the case of the EDPS ECR integration, the Hardware Manager implements the integration between the Openbravo Web POS and the serial port EDPS ECR protocol.
For implementing the EDPS ECR integration the Hardware Manager requires the plugin library (EDPSECR.jar) copied to the folder libext/ . A full guide to install and configure the hardware can be found here: http://wiki.openbravo.com/wiki/Retail:Hardware_and_Peripherals_Installation
Because the Payment events API isolates Openbravo from the implementation details of different payment integrations the following configuration must be done at the Hardware Manager level:
Payment method types configuration
For each payment type generated by the payment protocol it must be mapped in the configuration file openbravohw.properties, the Payment method search key corresponding to each payment type the search key of the Payment method to use.
EDPSECR.VISA = OBPOS_creditcard_visa EDPSECR.MASTER = OBPOS_creditcard_master ...
Localization
Localization messages generated by the payment protocol follows the java internationalization support https://docs.oracle.com/javase/8/docs/technotes/guides/intl/index.html with the resource name com.openbravo.edpsecr.i18n.labels.
For example, to create a new localization file for Greek a new file named labels_el_GR.properties must be located in the folder cpext/com/openbravo/edpsecr/i18n/ located in the hardware manager installation folder. This file must contain the same keys of the English location file located in the plugin jar file EDPSECR.jar file com/openbravo/edpsecr/i18n/labels.properties.
Literal translations can be delegated to Openbravo using ${MESSAGE_KEY} where MESSAGE_KEY is an AD_MESSAGES key.
For example the literal 'Process success: ${CPAY_ACTION_CASHUP_TITLE}' will be displayed as 'Process success: Payment terminal cashup'.
menu.ping = Ping terminal menu.batchclose = Batch close menu.batchtotal = Current batch total general.error.transaction = Error processing the transaction. system.error.type = Transaction type not supported. %s. Please contact an administrator. system.error.action = Action not supported. %s. Please contact an administrator. payment.error.euros = Only EUROS are supported. Please contact an administrator. payment.error.cancel = Transaction canceled by customer. payment.error.refusal = Transaction refused by processor. message.terminal = Terminal : %s message.info = Info : %s ping.success = Terminal communication success. batchtotal.title = Current Batch batchtotal.success = Report has been printed successfully. batchclose.title = Close Batch batchclose.success = Report has been printed successfully. Batch has been closed. batchclose.successempty = Report has been printed successfully. Batch is empty. batch.notransactions = No transactions batch.batchnumber = Batch number batch.approval = Approval batch.entriescount = Entries count batch.terminaltotals = Terminal totals batch.hosttotals = Host totals batch.salescount = Sales count batch.salessum = Sales sum batch.voidsalescount = Void sales count batch.voidsalessum = Void sales sum batch.refundscount = Refunds count batch.refundssum = Refunds sum batch.voidrefundscount = Void refunds count batch.voidrefundssum = Void refunds sum
Operation
Once everything is configured, the operation of the POS terminal is as usual. In the moment to process a payment transaction select the button with the Provider Group name configured and add the payment. In this case, a dialog will appear waiting for the terminal to process the payment. And after the payment is completed. The terminal will print a customer and merchant copy, the dialog will disappear and the payment line will appear in the Web POS application.
In Self Checkout the operation is similar.
Cashup
The cashup also executes the batch total functionality that prints a summary report of the payment terminal operations and also resets the totals to zero starting a new batch. This batch total function can be also executed from the menu option Payment terminal as explained in the next section.
Maintenance options
The menu option Payment terminal opens a dialog with details of the payment integration and the maintenance options Ping terminal, Current batch total and Batch close.
- Ping terminal is used to confirm the payment terminal has connectivity to perform payments.
- Current batch total prints a report with the summary of the current batch operations.
- Batch close prints a report with the summary of the current operations and reset the totals to zero starting a new batch.
Testing
For testing configure the URL of the payment event like this:
http://localhost:8090/process/EDPSECR?mode=mock&timeout=300000&acktimeout=1000
This mode simulates the EDPS ECR protocol at low level in the hardware manager plugin allowing to execute all the functionality implemented but without the real device: payments, refunds, voids, ping, current batch and batch close.
Using this mode allows not only to verify the correct behavior of all the functionality without having the real payment terminal connected to a serial port but also, in case of error isolate easily the source of the error, if it is coming from Openbravo or from the payment terminal.