Retail:Developers Guide/Payment Providers

Contents 1 Introduction 2 Getting started 3 Openbravo Module 3.1 Backend Definition 3.2 Payment and Refund enyo component 3.3 Standard Payment Provider payment and refund implementation 3.4 Void enyo component 3.5 Standard Payment Provider void implementation 4 Hardware Manager plugin 5 Current implementations

Introduction

This functionality allows payment methods who share the same payment provider showing only one payment button. Depending the card processed by the payment provider the appropriate payment method is added to the WebPOS receipt.

This simplifies and reduces mistakes in the payment flow. The cashier is no longer responsible of selecting the correct payment method depending on the customer card. Now is the payment provider who takes this responsibility.

In this document it is explained how to integrate a new Payment Provider in Openbravo using this new functionality.

The user guide for this functionality can be found in the document Payment Methods grouping by Provider User Guide.

Getting started

To begin it is needed to have the technical documentation, a testing device. If it is a pinpad device test cards. Also it is very important to have a direct technical contact who can answer in case of any impediment found during the development.

Next, it is needed to identify the architectural model to use in the implementation. To do this follow the Payment Gateways Guide, depending on the payment provider choose the architectural model that better fits with the technical implementation of the payment provider.

As an especial case if the payment provider fits the Direct Device Connection architectural model it may be possible to use the Standard Payment Provider included in Web POS and only a Hardware Manager plugin will be needed to implement. This is possible if all the configuration of the payment provider is done in the device payment and it is not needed payment provider configuration in Openbravo or there is no extra information to be sent the the payment provider apart from the amount and type of transaction (Payment, Refund, Void) and also there is no extra information to process the result apart from the transaction status, success or failure, the transaction message and the key value to select the payment method. If this is the case, go directly to the Hardware Manager Plugin section.

Openbravo Module

First it is needed to create a new module. To do this follow the Modularity_Concepts document. Once it is created you can start defining the payment provider integration. The module must depend on Web POS module

Backend Definition

To define the new provider implemented in the module, as System Administrator verify the module is in development status and open the Reference window, find the record Provider defined in the Web POS module. Go to the tab List Reference and create a new record for each provider implemented in the module. Usually it is defined one provider per module.

The values to define here are:

• Module: Select your module.
• Search key: The unique identifier of the provider. It defines the name of the javascript enyo component that implements the provider in Web POS.
• Name: The name that apears in the Provider drop down list of the Provider group configuration tab.
• Description: An extended description of the provider.

After the reference is defined, rebuild the application before going to the next step. Rebuild is needed because references require java code generated by the build process.

Then you need to define all the method types the implemented provider can handle. This is a list that defines the what is the payment method to select depending on the cardlogo value returned by the provider. As System Administrator go to the Payment Method Type window and add a new record for each payment method handle by the provider to implement.

The values to define in each record are:

• Module: Select your module.
• Provider: The provider defined in the previous step.
• Search key: The unique identifer the implemented provider can handle. This is the value used to match the cardlogo value returned.
• Name: The name that appears in the Payment Method Type field of the Payment Method configuration tab.

Payment and Refund enyo component

The Web POS client implementation of the provider for payments and refunds it is an enyo component with the name of the Search key in the List Reference definition.

enyo.kind({
  name: 'MyProviderImplementation',
  ...

This compoment has to implement the following fields:

checkOverpayment: Boolean value that if true checks before executing the payment proces if the amount to process creates an overpayment over the total of the receipt, and if it does, cancels the payment or refund process.

providerComponent: Enyo component to display inside the payment process dialog when invoking the payment process. This component can be just an information component or can include UI widgets to request input from the cashier. If null, just the default dialog will be displayed during procesing.

processPayment(): Function invoked when processing a payment or refund. This function receives a parameter with the information of the transaction to process and return a javascript Promise.

Function parameters

• receipt: The receipt model.
• currency: The currency ISO code of the amount to process.
• amount: The amount to pay or refund. It is always a positive value.
• refund: Boolean value that indicates to pay or to refund.
• providerGroup: The provider group model.

Promise resolved result

• transaction: Optional. Identifier of the transaction. This value depends only on the provider implementation.
• authorization: Optional. Identifier of the authorization procesed. This value depends only on the provider implementation.
• properties.cardlogo: Identifier used to select the payment method to assing the transaction.
• properties.cardmasked: Optional. Information of the payment method used. Usually the credit card number last four numbers. It must not include sensible information of the customer.
• properties.voidproperties: Value that will be sent in case the transaction is voided by the cashier. It must include all the information needed by the provider in order to properly cancel the transaction. In case transactions cannot be voided, it has to be empty.

Promise rejected result

• message: Message to display in case of getErrorMessage() function is not defined.

getErrorMessage(): Optional function, that if defined will be invoked after processPayment is rejected. It will receive as parameter the Promise rejected value, and must return the message to display to the cashier informing the transaction has been rejected.

Standard Payment Provider payment and refund implementation

In case the provider is implemented using a Hardware Manager plugin, the enyo component used to implement the provider can subclass the enyo component OBPOS_StandardProvider that includes all common functionalities to call and process responses to the Hardware Managery payment endpoint.

enyo.kind({
  name: 'MyProviderImplementation',
  kind: 'OBPOS_StandardProvider',
  ...

This compoment has to include the same fields as other implementations except processPayment() that is implemented by OBPOS_StandardProvider. The new fields that has to be defined are:

populatePaymentRequest(): Function invoked when processing payments with the request before it is sent to the Hardware Manager and must return the new request. This functions is used to include new fields needed by the payment provider Hardware Manager plugin. The standard request has the following fields:

• type: Transaction type. 0 for payments, 1 for refunds.
• currency: Currency ISO code of the amount to process.
• amount: Amount to process.
• properties.provider. Search key of the payment provider as defined in the List Reference.

populateRefundRequest(): The same as populatePaymentRequest() function for refunds.

Void enyo component

The Web POS client implementation of the provider for voiding payments and refunds it is an enyo component with the name of the Search key in the List Reference definition followed by Void.

enyo.kind({
  name: 'MyProviderImplementationVoid',
  ...

This compoment has to include the following fields:

voidConfirmation: Boolean value that defines whether or not to show a confirmation dialog before executing the void process.

providerComponent: Enyo component to display inside the payment process dialog when invoking the void process. This component can be just an information component or can include UI widgets to request input from the cashier. If null, just the default dialog will be displayed during procesing.

processVoid(): Function invoked when processing void. This function receives a parameter with the information of the transaction to process and return a javascript Promise.

Function parameters

• receipt: The receipt model.
• payment: The payment model to void. As a note, in payment.get('paymentData').properties.voidproperties will go the value of properties.voidproperties returned when the payment was resolved.

Promise resolved result

No value is required to return. After resolving the promise the payment line will be removed.

Promise rejected result

• message: Message to display in case of getErrorMessage() function is not defined.

The most simple implementations of this functions is when voiding always succeds, that is implemented this way:

processVoid: function (data) {
  return Promise.resolve();
}

And when always fails because transactions cannot be voided from WebPOS. This may be implemented this way:

processVoid: function (data) {
  return Promise.reject({
    message: OB.I18N.getLabel('CANNOT_VOID');
  });
}

Where CANNOT_VOID is the key for the translateed message to display to the cashier. This way it is not needed to define getErrorMessage() function

getErrorMessage(): Optional function, that if defined will be invoked after processVoid is rejected. It will receive as parameter the Promise rejected value, and must return the message to display to the cashier informing the transaction has been rejected.

Standard Payment Provider void implementation

In case the provider is implemented using a Hardware Manager plugin, the enyo component used to implement the provider can subclass the enyo component OBPOS_StandardProviderVoid that includes all common functionalities to call and process responses to the Hardware Managery payment endpoint.

enyo.kind({
  name: 'MyProviderImplementationVoid',
  kind: 'OBPOS_StandardProviderVoid',
  ...

This compoment has to include the same fields as other implementations except processVoid() that is implemented by OBPOS_StandardProviderVoid. The new fields that has to be defined are:

populateVoidRequest(): Function invoked when processing payments with the request before it is sent to the Hardware Manager and must return the new request. This functions is used to include new fields needed by the payment provider Hardware Manager plugin. The standard request has the following fields:

• type: 2 for void.
• currency: Currency ISO code of the amount to process.
• amount: Amount to process.
• properties. The value that comes in payment.get('paymentData').properties.voidproperties of the parent processVoid() function.

Hardware Manager plugin

To implement the Hardware Manager plugin follow the guide How to create a new device driver, the section Payment device driver implementation. Note that in order to properly select the right payment method, the value returned in properties.cardlogo must be one of the Search key defined in the Payment Method Type window.

Current implementations

The following implementations can be used as an example on how to create a new Payment Provider implementation:

• CHASE Paymentech