Hybris – Openpay Payment Plugin

Integration Guide

Objectives

The Openpay – SAP Hybris Commerce Cartridge allows seamless integration between SAP Hybris Commerce and Openpay payment gateway. New option is added in Hybris checkout flow to pay with Openpay under certain conditions.

Functional Overview

This cartridge includes new payment method as Openpay in checkout flow under payment section. This section is only enabled if cart lies under specific price range, which is configured in Hybris Configuration section. Successful purchase flow can be done through Openpay payment method, cancel flow and refunds can also be handled.

Limitations

For newer Hybris versions Hybris CMSCockpit might not be available for components configured like Openpay payment logo, error message. This can be configured from backoffice as well.

Compatibility

Openpay payment cartridge is built in Hybris 6.2.0. Migration is required to use the cartridge in upper versions. Not compatible with lower versions. This cartridge is built for demo stores i.e. apparel-uk, electronics and apparel-de of B2C accelerator. All UI components are used OOTB.

Installing and Configuring Openpay Payment Plugin

Installation Steps

Installation of Openpay payment cartridge in SAP Hybris platform is as follows:

Already assumed that Hybris is installed on your machine, if not please install Hybris suite with B2C accelerator recipes
Fetch the plugin required extensions (either a zip file or take a pull from GIT repo if available)
The code structure will look like

If working on new Hybris suit then copy entire custom folder under {Hybris_Dir}/hybris/bin, else if its old suite and custom folder is already available just copy the extensions to the already created custom folder
You can create symbolic link for custom folder as well from repository to Hybris/bin so that updated code can be reflected automatically
Copy to content of {gitRepo}/config/customize to {HYBRIS_DIR}/hybris/config/customize
Copy content of files from config folder and copy them under {Hybris_Dir}/hybris/config

LocalExtensions.xml

<!– Openpay Integration–>

<extension name=’openpaypaymentaddon’ />

<extension name=’openpayintegration’ />

<extension name=’openpaybackofice’ />

Local.properties

Copy these content to local.properties file of you Hybris suite. Please change the domain name for redirectUrl and failUrl according to your domain if any.

redirectTokenFieldName=TransactionToken
jarResourceCmsValue=jar\:com.openpay.setup.OpenpayPaymentAddonInitialDataSetup&/openpaypaymentaddon/import/cockpits/c mscockpit
planCreationType=Pending
openPayMaxValue=1000
openpayPassword=EC3C629D-CF23-4045-A07A-38A21D39AC16
openPayMinValue=150
redirectUrl=https\://localhost\:9002/yacceleratorstorefront/checkout/multi/payment-method/placeOrderWithOpenPay
failUrl=https\://localhost\:9002/yacceleratorstorefront/cart
customerQuality=-1
openpayEndPointUrl=https\://api.training.myopenpay.com.au/v1/merchant
openpayUserName=OP 3340
chargeBackCount=-1
OpenPayRedirectUrl=https\://retailer.myopenpay.com.au/websalestraining/?TransactionToken\=
maxRetry=3
origin=ONLINE

Note: AuthToken provided by Openpay would look like
3-373|180D731A-F9C8-437B-8FC0-8341196D9CF0

openpayUserName: 3-373

openpayPassword: 180D731A-F9C8-437B-8FC0-8341196D9CF0

Now go to / {Hybris path}/hybris/bin/platform open cmd and run following commands to build the pluginNow please update the domain name for failrUrl and redirectUrl, if using localhost then fine, if using something else, please update it and save the file.This can be changed from HAC as well but to persist it after server restart please update to this file as well.

Windows	MAC/Linux
setantenv.bat	. ./setantenv.sh
ant customize	ant customize
ant addoninstall -Daddonnames=’openpaypaymentaddon’ -DaddonStorefront.yacceleratorstorefront=”yacceleratorstorefront”	ant addoninstall -Daddonnames=’openpaypaymentaddon’ -DaddonStorefront.yacceleratorstorefront=”yacceleratorstorefront”
ant clean all (after success)	ant clean all (after success)
hybrisserver.bat	./hybrisserver.sh

Once ./hybrisserver.sh is completed with success it looks like –

If its new installation (installing Hybris for the first time) just go to Browser and type URL {https://localhost:9002/} login with credentials admin/nimda. Go under Platform tab > Initialisation and press button Initialize and then perform the next step as well. If already initialised once jump to next step directly.

Go to Browser and type URL {https://localhost:9002/} login with credentials admin/nimda. Go under Platform tab > Update, select openpayintegration,openpaybackoffice amd openpaypaymentaddon and run update

Once completed open backoffice by URL https://localhosthost:9002/backoffice. Check whether cron jobs are added or not by going to System >Background Processes > Cronjobs Automatic cronjob for limits is configured which has to be run once manually during installation

Now cartridge is installed successfully

Select the openpayGetLimitConfiguredCronJob and run the cron job once as it if first time installation. Go to Backoffice (https://localhost:9002/backoffice) > Login with credentials (admin/nimda) > System tab > BackgroundProcess > CronJobs > Select cron job openpayGetLimitConfiguredCronJob

If its new installation for Hybris 6.2 register does not work OOTB due to some recaptcha private and public key, so please just disable the captcha from backoffice and then registration works. We can checkout as guest as well. This is just in case registration is required.

NOTE : If Hybris return functionality is used OOTB please replace {Hybris_Dir}/hybris/config/customize/ OOTB_REFUNDS/ CaptureRefundAction.java with OOTB refund action class in fulfilmentprocess or ordermanagement extension for using OOTB returns for Openpay as well. Second add dependency of openpayintegration to your fulfilmentprocess or ordermanagement extension.

Configuration of Cron Jobs

As discussed in last step two cron jobs are configured in backoffice after successful installation of payment plugin.

openpayGetLimitConfiguredCronJob

Cron job configured the minimum and maximum limit price to pay order using Openpay payment method. This cron jobs mainly makes a call to SDK layer and get the price range. For first time plugin installation this job has to be configured manually once. It’s an automatic job which runs every day at 12:00 PM.

Once limits are configured they can be checked in Hybris Administration control. Go to https://localhost:9002 > login using password (nimda)> Go to Platform tab > select configuration tab > search with keyword ‘Openpay’

openpayUpdateOrderStatusCronJob

Cron job is configured to check the status of orders paid with Openpay but the payment status is in pending state. This cronjob is currently configured with trigger of running everyday at 12:00 PM.

Triggers can be changed from backoffice for cron jobs, please check the steps below:

Open particular cronjob to update the scheduled trigger by Go to Backoffice (https://localhost:9002/backoffice) —> Login with credentials (admin/nimda) > System tab > BackgroundProcess > CronJobs > Select one cron job to be updated like openpayUpdateOrderStatusCronJob. Go to highlighted tab Time Schedule

Go to trigger attribute in Time Schedule tab and double click the already added trigger.
After double clicking the trigger window appears same as below, update the value of cron expression. Example given expression 0 0 12 * *? Means run cron job at 12:00 everyday. Example want to run cron job after every 30 minutes so expression will be updated as 0 30 0 * * ?

Testing Openpay Plugin

Go to demo site storefront to start with placing order with Openpay. On browser add URL https://localhost:9002/yacceleratorstorefront/?site=electronics. The highlighted domain can be changed based on server. Taking an example we deploy code to staging environment and test it from any browser, then the URL becomes https://serverName:9002/yacceleratorstorefront/?site=electronics where serverName is name or id of server like ec1-23-45-216-100.us-west-2.compute.amazonaws.com

Now select products and proceed to checkout

Create a new user or login or checkout as guest login from checkout page. For testing use email ecommerce@xx.yy

After login successfully we move to checkout page to add following details.
After successfully adding shipping details we move to payment section where along with OOTB payment method Openpay payment method is added. This method is selected only if order price is between given range configured.

On clicking “Choose Openpay to place order” create new order api is called from Openpay SDK and with transaction id and redirect URL we are redirected to Openpay to select and submit the plan.
Use test login credentials as
Username: ecommerce@xx.yy
Password: Test@1001
Check logs in Hybris console terminal side by side.

After login to Openpay perform further steps to submit the plan by giving card details and choosing the plan.

After submitting the plan successfully, order is created in Hybris and we land to order confirmation page.
If cart price is not in range of configured values we cannot move further with payment option as Openpay.

If we are redirected to Openpay but instead of submitting order we select “return to shop” or if browser is interrupted or closed abruptly order is not created in Hybris and we land on cart page.

Once order is placed successfully in Hybris we can check order in backoffice and we can perform refunds if possible. Just in above screenshots check we created order with order id “00001010”, check order confirmation page. We check the order with same id on backoffice.

Login to backoffice (https://localhost:9002/backoffice). Login with credentials (username: admin / password: nimda) and go to Order tab.

When we placed order with Openpay, order status and plan id is stored in DB but not editable.
For refunds, order should be shipped or pickup complete (consignment should be created) and Openpay order status should be OPENPAY_APPROVED to activate refunds. Refund button is available on editor area of tab as shown in screenshot above.

Before clicking on refund button add details on refund tab like whether its full or partial refund, amount to be refunded. If its full refund just select ‘Yes’ and save the form, value will be persisted automatically. For partial refund select ‘No’ and add amount to be refunded.

Now click on refund button and on confirmation, refund is successfully completed if data is correctly sent.

Once order is fully refunded, refund tab is hidden and order status is updated to OPENPAY_FULLY_REFUNDED. Refund button is also disabled.

We can check the return history from same tab under return process attribute. If its full refund one entry is added, for partial refunds multiple entries are created.

Double click on the above return request entry to check refund details

For partial refunds, we can do multiple partial refunds, every time amount to be refunded is calculated again and updated.
We can perform multiple partial refunds by updating the value and history we can check through return request attribute.

Test Credentials

This section provides the credentials for test user and test merchant account on Openpay Training Environment to create and check your Openpay plan.

Test User

Username: ecommerce@xx.yy
Password: Test@1001

Test Merchant / Retailers Account

https://retailer.myopenpay.com.au/training
Username: test_user
Password: Test@123

Configuration of Openpay Icon and Text

Configuration of Openpay Icon and text for storefront using cmscockpit

We can configure Openpay icon by browsing to cmscockpit. https://localhost:9002/cmscockpit
Just select login, as credentials are added automatically. Based on which store we are using for online shopping we select the catalog with staged using for online shopping we select the catalog with staged version, changes will be done in staged version and then catalog will be synchronised. Select multi checkout summary page for particular catalog.

Double click on page or click the edit icon for configuration of components.

Select Logo component to change the logo

As the logo changes the component synchronise button changes to red from green, just click on the button to render changes to frontend.

Now in similar fashion text can be changed for error component.

Configuration of Openpay Icon and Text for Storefront using Backoffice

For some new Hybris versions, cmscockpit is not used, so we can do above configurations using backoffice

Logon to backoffice and go to tab WCMS > Components.

We have created components by id ErrorPayingWithOpenPayParagraphComponent and PayWithOpenPaySimpleBannerComponent. Search these components in search box

Double click on the selected row above and go to Administration tab and change the media

Similar way the text component can be changed. Now go to catalogs and synchronise the catalog to make changes persist to the online version.

Configuration of Openpay API Properties

Configuration properties for API like endpoint URL, authentication password URL, redirect URL etc. are defined in /hybris/config/local.properties file. Any changes for API configurations values will be done under this file. Changes done under this file are reflected after build and server restart.

After changing the property, please build the server again by running the following commands

Setantenv.bat
Ant clean all
Hybrisserver.bat

After success, changes of these properties are visible under Project configuration properties of Hybris admin console

Demo Site

Shows the placement of all the Openpay widgets and assets. You can test an Openpay plan creation on this site.