View source | Discuss this page | Page history | Printable version   

Retail:Developers Guide/Payment Providers

Contents

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.

Bulbgraph.png   Important: To use this functionality you will need a compatible payment provider implementation. Previous payment provider and refund providers implementations are not compatible with this functionality. The reason is that now payment provider implementations have to return an identifier to select the right payment method.

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.


Providerreference.png


The values to define here are:

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.


Providerpaymentmethodtype.png


The values to define in each record are:

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

Promise resolved result

Promise rejected result

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:

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

Promise resolved result

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

Promise rejected result

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:

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:

Retrieved from "http://wiki.openbravo.com/wiki/Retail:Developers_Guide/Payment_Providers"

This page has been accessed 817 times. This page was last modified on 8 May 2018, at 13:50. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.