Projects:Retail Payment Providers/Technical Documentation

Introduction

This documents describes the project that offers support for Payment Providers using devices that do not offer direct integration with web browsers. In this case the Hardware Manager is needed to handle the comunication with the payment device.

Hardware Manager architecture

Hardware Manager includes a plugable java classes architeture that allows to include new payment providers without having to modify and recompile the main Hardware Manager. This architecture is based in the java standard ServiceLoader API that is already used in Hardware Manager to offer a plugable architecture for POS devices. The documentation that describes how to implement new device drivers is described in the How to create a new device driver document.

The API provided by the Hardware Manager is based in an request where request parameters and result are JSON Object with the following specification:

Request

• type: The type of the transaction: 0, Sale. 1, Refund. 2, Void transaction.
• terminal: The terminal ID that executes the payment request.
• transaction: The transaction ID that reffers this new transaction. This is used to refund or void a previous transaction.
• amount: The amount to pay, refund or void.
• currency: The currency of the amount to pay, refund or void.
• properties: A map of properties used by different payment providers.
• test: Used to identify whether this transaction is real or not. This property is used for testing purposes in development or deployment.

Result

• result: Result of the transaction: 0, Success. 1, Authorization fail. 2, Error.
• resultCode: Result code returned by the payment provider.
• resultMessage: Message returned by the payment provider.
• transaction: The ID of this transaction used to identify this transaction in further transactions.
• authorization: the ID of the authorization returned by the payment provider.
• properties: A map of properties returned by different payment providers.
• request: the payment request parameters that originated this result.

Web POS architecture

Web POS architecture for payment providers is described in the External Payment Providers document. In the case of Payment Providers using this architecture based in devices connected to the Hardware Manager, an http request from Web POS to the Hardware Manager must be executed using the parameters and response specification described in the previous paragraph.

Following there is a sample method of a javascript object that executes a payment transaction invoking the Hardware Manager.

 invokePaymentServer: function () {
   var request = {
     type: 0,
     transaction: null,
     terminal: 'POS1',
     currency: 'EUR',
     amount: 10.50,
     properties: {}
   };
   return new enyo.Ajax({
     url: 'http://localhost:8090/payment',
     cacheBust: false,
     method: 'POST',
     handleAs: 'json',
     contentType: 'application/json;charset=utf-8'
   }).go(JSON.stringify(json));
 }

In the Openbravo repository org.openbravo.retail.paymentprovider there is an Openbravo module that implements a basic external payment provider that invokes the Hardware Manager.

Testing

The Hardware Manager includes a mock payment provider used for testing purposes called Screen Payment Device. In the Payment tab of the Hardware Manager user interface can be defined the result that will be returned when executing a payment transaction coming from Web POS.

It is also included a Test payment button that executes a payment transaction using the payment provider currently configured. All payment transactions executed using the Test payment button sets the test parameter to true to avoid executing real payment transactions from the Hardware Manager.