H Appendix: Pay By Link (PBL) Integration with Adyen Payment Provider

This section describes the Pay By Link (PBL) Integration with Adyen Payment Provider.

Overview

Xstore can now support Pay By Link tenders, allowing customers to tender for transactions remotely and also allowing payment using a number of alternative payment types as supported by the payment provider and retailer.

The Pay by Link functionality allows a sales associate to provide a way for a customer to pay for merchandise without ever handing over any sort of payment item or communicating any sort of payment information to the sales associate.

Instead, the customer will be presented with a link (url) which they can visit in order to enter their payment information securely on the payment providers payment checkout webpage, and pay for their merchandise.

Two types of Pay By Link tenders are supported:

• PBL Customer Not Present This tender is typically used when the customer is not present in the store, but is instead on the phone to the sales assistant, creating an order such as Send Sale. The PBL link (url) is emailed to the customer, which the customer will click, taking them to the payment providers payment checkout webpage.

• PBL On the Payment Terminal

  This tender is typically used when the customer is in the store and wishes to pay with an alternative tender such as various wallet or other payment types.

  The PBL link (url) is displayed on the payment terminal as a QR Code, that the customer can scan using their cell phone, taking them to the payment providers payment checkout webpage.

  An Xcenter webservice needs to be enabled and configured, to process completed PBL Customer Not Present payments in Xstore. This service processes PBL payment result notifications from the payment provider.

Security Considerations

The new REST service mentioned in the Web Service Changes section below is exposed for On-Premise installations of Xcenter.

On-Premise installations of Xcenter use basic authentication. For the basic authentication for the Adyen service, a new user role and a new user will need to be setup in the application server container.

This new user is the one that will be given to Adyen, so that Ayden may contact the service that is exposed for them (and only the service that is exposed for them).

A security role named AdyenUsers has been defined in Xcenter's web.xml file and associated with authentication for the Adyen notification service. The role and the user will need to be setup depending on the container that a retailer is using. Below are some basic directions on how to do that setup. More specific information about each container can be found in the container's own documentation.

Tomcat

In the directory where Tomcat is installed, go to the conf directory and add the new role and user to the tomcat-users.xml file.

Note:

AdyenUsers is the name of the role that must be used.

tomcat-users.xml excerpt:
<role rolename="AdyenUsers"/>
<user username="adyen" password="adyen" roles="AdyenUsers"/>

Jetty

Run the following command from a command prompt, where <path-to-dtv-password.jar> is the directory where the file dtv-password.jar exists.

title Prompt for New Jetty Password:

java -cp <path-to-dtv-password.jar>/dtv-password.jar oracle.retail.xstore.passwd.impl.Ssha2Hasher

That will prompt you for your Adyen user's password. Type your new password and press Enter.

The output will be a hashed password that you need to copy into the passwds file in the etc directory where Jetty is installed, along with other user information.

The format of the line that should be added to the file is as follows, with ${adyenAuthUserName} being replaced with the Adyen user name and ${xcenterAuthPasswordHash} being replaced with the hashed password that was output by the command above.

AdyenUsers is the name the of security role and that is the value that must be used for it.

title Line Format for Jetty passwds File:

${xcenterAuthUserName}:${xcenterAuthPasswordHash}:92464520400:0:0:AdyenUsers

Weblogic

The Xstore Suite Implementation and Security Guide, section Install an Application Server: WebLogic, Jetty, or Tomcat, has instructions on how to use WebLogic's admin tools to add users and groups for the standard Xcenter users.

The same instructions can be followed to add the appropriate Ayden user, substituting AdyenUsers for XcenterUsers as the name of the group.

Web Service Changes

In order to be notified when a PBL payment has been made, Adyen requires that a service be exposed to which payment result notifications can be sent. This service has been added to Xcenter.

Service Name: PayByLinkNotificationResource

Version: V1

Description: A RESTful web service endpoint that receives notifications from Adyen about payments that have been made using payment links. The service URL that needs to be configured in Adyen is:

<xcenter_protocol>://<xcenter_host>:<xcenter_port>/xcenter/rest/adyen/v1/<organization_id>/notification

Additional Details

Pay By Link tenders are not available in Xstore by default. In order to make the Pay By Link tenders available for use within Xstore, the "Payment By Link Tenders" base feature must be enabled in Xadmin.

At a technical level, this adds the config path entry ":paybylink" to the xstore.config.path.base.features property in configPath.properties.

Xstore queries Xcenter periodically for payment results. The interval for this result polling is specified on a Spring scheduled task configuration.

A copy of the base version of the Spring bean definition is included below.

If you wish to override it to change the polling interval, you can copy this entire bean definition to a "spring" sub-directory in a config override directory (like :localconfig/spring/local-overrides.xml or whatever your local override directory is).

Spring Scheduled Tasks Bean Definition for Xstore:

<task:scheduled-tasks scheduler="springTaskScheduler">
  <task:scheduled ref="xenvPasswordFileCreationTask" method="run" fixed-delay="900000" initial-delay="0" />
  <task:scheduled ref="autoClockOutTask" method="reclockFromMidnight" cron="0 0 0 * * ?" />
  <task:scheduled ref="environmentHelper" method="hasUpdateGracePeriodExpired" initial-delay="60000" fixed-delay="20000" /> 
  <!-- 86400000 millis is 24 hours -->
  <task:scheduled ref="sensitiveDataLoggingCheck" method="check" fixed-rate="86400000" initial-delay="0" /> 
  <!-- 3600000 is once per hour -->
  <task:scheduled ref="extensionStoreConnectivityCheck" method="check" fixed-delay="3600000" initial-delay="10000" />   
  <task:scheduled ref="payByLinkAdyenResultCheckTask" method="checkAndProcessResults" fixed-delay="900000" initial-delay="120000" />   
</task:scheduled-tasks>