1 User Manual

1.1 Plugin Extension

Add extension to your SAP Commerce Cloud (previously known as SAP Hybris) project. Refer Implementation guide document to know the steps included in adding extension into your SAP Commerce Cloud project 

1.2 Manage Account

In SAP Commerce Cloud backoffice, See the wallee Account section, which shows the accounts/mode. Here the user can switch between the payment interfaces. We recommend to manually set only one account/mode as active at a time. If both accounts/mode are active, it will take PaymentPage as default account. 

Figure 1.1.1: wallee account section in the backoffice view

Figure 1.1.2: wallee account section edit mode

1.3 Payment Modes

Installing the Wallee Payment Solution for SAP Commerce Cloud extension will provide you with user configured payment methods in wallee which can be viewed in Payment Methods Configuration in user’s space in wallee. Here new standard payment modes can be added as required.

1.4 Manage Transactions

Transactions and their states can be viewed in user’s space in wallee. Initiated transactions are listed here.

1.5 Confirm transaction Before Place Order (Beta Version)

This functionality is managed inside the wallee account in the backoffice. It provides two options: 

  • ON
  • OFF

Figure 1.4.1: Confirm transaction Before Place Order mode option in a wallee account

  • If the confirm transaction before place order mode is ON, then the transaction is confirmed and the status/properties cannot be changed anymore.
  • If the confirm transaction before place order mode is OFF, then most of the properties can be modified until the transaction is moved to the state confirmed.

2.0 Software License Agreement 

This Software License Agreement ("Agreement") is between you (both the individual downloading and/or installing the Software and any legal entity for or on behalf of which the individual is acting) ("You" or "Your") and PIT Solutions AG. ("Licensor"). 

THIS LICENCE AGREEMENT CONTAINS THE TERMS AND CONDITIONS TO USE SOFTWARE. BY CLICKING ON THE “ACCEPT” BUTTON, YOU ARE CONSENTING TO BE BOUND BY AND ARE BECOMING A PARTY TO THIS AGREEMENT. IF YOU DO NOT AGREE TO ALL OF THE TERMS OF THIS AGREEMENT, CLICK THE “DO NOT ACCEPT” BUTTON WHICH WILL STOP YOUR ACCESS AND USE OF THE SOFTWARE. IF YOU HAVE ALREADY INSTALLED THE SOFTWARE BUT DO NOT AGREE TO ANY TERM OR CONDITION IN THIS AGREEMENT, THEN PLEASE UNINSTALL THE SOFTWARE IMMEDIATELY.

TAKING ANY STEP TO SET UP, DOWNLOAD OR INSTALL THE SOFTWARE MEANS THAT YOU ACCEPT ALL OF THE TERMS OF THIS LICENSE AGREEMENT. PERMISSION TO DOWNLOAD, INSTALL AND/OR USE THE SOFTWARE IS EXPRESSLY CONDITIONED ON YOU AGREEING TO AND FOLLOWING THESE TERMS.

THE SOFTWARE IS TO BE USED SOLELY IN CONNECTION WITH THE THIRD PARTY SOFTWARE AND YOU MUST SATISFY YOURSELF THAT THIS SOFTWARE IS SUITABLE FOR YOUR NEEDS AND THAT YOUR SYSTEM SATISFIES THE REQUIREMENTS FOR THE USE OF THIS SOFTWARE AS SET OUT IN THE DOCUMENTATION.

PARTIES, THEREFORE, AGREE AS FOLLOWS: 

  • Definitions
    • Capitalized terms in this Agreement will have the following meanings:
“Agreement” means this Licence Agreement and any documents referred to in this Agreement;
"Documentation" means written documentation, specifications and help content made generally available by Licensor to aid in installing and using the Software, or otherwise provided by Licensor to you in connection with the Software.
“Software” means Wallee Payment Solution for SAP Commerce Cloud, the data supplied with such software, executable program modules thereof, computer readable associated media, upgrades, and updates of the software provided to you by the Licensor.
“Third Party Software” includes the third party software with which the Software is designed to be used, as
described in the Documentation.
  • Grant of License
    • In consideration of the mutual covenants and subject to the provisions contained in this Agreement, Licensor hereby grant You a limited, revocable, non-exclusive, non-transferable, royalty-free licence without the right to sublicense
      • to install a single copy of the Software on Your equipment containing the Third Party Software, solely for the purpose of using the Software in connection with the Third Party Software and Licensor’s own products, as described in the Documentation ("Authorised Use"); 
      •  to use the Documentation in support of Your Authorised Use; and 
      • to make one copy of the Software solely for backup purposes, provided that all titles and trademark, copyright, and restricted rights notices are reproduced on the copy.
    • Licensor retains all right, title and interest in and to the Software and Documentation. Licensor owns or retains all patents, copyrights, trademarks, trade secrets and other intellectual property rights in the Software and Documentation and any derivative works thereof. You do not acquire any other rights, express or implied, beyond the limited license set forth in this Agreement.
    • Licensor has no obligation to provide support, maintenance, upgrades, modifications or new releases for the Software or Documentation under this Agreement. 
    • You undertake not to:
      • rent, lease, sub-license, loan, translate, merge, adapt, vary or modify the Software or Documentation;
      • make alterations to, or modifications of, the whole or any part of the Software, nor permit the Software, or any part of it, to be combined with, or become incorporated in, any other software other than the Third Party Software as described in the Documentation;
      • provide or otherwise make available the Software in whole or in part (including but not limited to program listings, object and source program listings, object code and source code), in any form to any person other than your employees without the prior written consent of the Licensor;
      • distribute, publish, or otherwise provide copies in relation to the Software to any third party;
      • pledge, hypothecate, alienate or otherwise encumber the Software to any third party;
      • change, modify, enhance, reverse-engineer, decompile, or disassemble the Software, or create derivative works based on the whole or any part of the Software, or attempt to do either of the foregoing; or
      • do anything which is not expressly allowed under this Agreement
  • Your Personal Information
    • For downloading the Software, you may have to provide your name, email address, address, and telephone number to the Licensor which will be subject to the terms in the Privacy Policy.
  • No Liability for Licensor
    • Licensor does not own or control Third Party Software or other software which are placed in the same environment as that of the Third Party Software. Likewise, Licensor does not own or control any websites within which the Third Party Software or other related software is placed.
    • Accordingly, all your access and use of the Third Party Software and third party websites is at your own risk and costs. Licensor is not liable for any loss or damage caused to you by your access or use of Third Party Software or third party websites.
  • Downloading the Software
    • Your acceptance of this Agreement will signify your unconditional agreement to all the terms and conditions contained in this Agreement. Upon your acceptance of this Agreement, you will be permitted to download a copy of the Software for Your use in accordance with the Documentation; and
  • Warranty Disclaimer
    SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT ANY REPRESENTATIONS OR WARRANTIES, AND YOU AGREE TO USE THEM AT YOUR SOLE RISK. TO THE FULLEST EXTENT PERMISSIBLE BY LAW. LICENSOR EXPRESSLY DISCLAIMS ALL WARRANTIES OF ANY KIND WITH RESPECT TO THE SOFTWARE AND DOCUMENTATION, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, SATISFACTORY QUALITY, ACCURACY, TITLE OR NONINFRINGEMENT OF THIRD PARTY RIGHTS.
  • Limitation of Liability and Remedies
    IN NO EVENT WILL LICENSOR OR ITS AFFILIATES BE LIABLE IN CONNECTION WITH THIS AGREEMENT OR ITS SUBJECT MATTER, UNDER ANY THEORY OF LIABILITY, FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR DAMAGES FOR LOST PROFITS, REVENUE, BUSINESS, INFORMATION, SAVINGS, DATA, USE, INTERRUPTION TO BUSINESS, OR COST OF SUBSTITUTE PROCUREMENT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR IF SUCH DAMAGES ARE FORESEEABLE. IN NO EVENT WILL LICENSOR’S LIABILITY FOR ALL DAMAGES EXCEED THE AMOUNTS ACTUALLY PAID BY YOU TO LICENSOR FOR THE SOFTWARE OR IF NO AMOUNT IS PAID, THEN AN AMOUNT OF $100. YOU SHALL NOT INSTITUTE ANY ACTION IN ANY FORM ARISING OUT OF THIS AGREEMENT MORE THAN ONE (1) YEAR AFTER THE CAUSE OF ACTION HAS ARISEN. 
  • Term
    • This Agreement is effective from the time you download or start using the Software and will remain valid until terminated. Licensor may terminate this Agreement at any time upon Your breach of any provision. If this Agreement is terminated, you will stop using the Software, permanently delete it from the equipment where it resides, and destroy all copies of the Software and Documentation in Your possession, confirming to Licensor in writing that You have done so. Sections 2, 3, 4, 5, 6, 7, 9, and 10 will continue in effect after this Agreement's termination.
  • Confidentiality
    • You acknowledge that this Agreement and its contents and other information, including, without limitation, information on or about the Software, source code, functionalities, Documentation, other technical information, know-how, and trade secrets that You receive in connection with this Agreement is Licensor’s confidential information (“Confidential Information”). You will use reasonable diligence, which will in no event be less than the degree of care which You use in respect to Your own confidential and proprietary information of like nature, to prevent the unauthorized use, disclosure, reproduction, or distribution of Confidential Information to any other individual, corporation or entity. You shall not use the Confidential Information for Yourself except for the limited licence granted under this Agreement.
  • General
    • This Agreement constitutes the entire agreement between the parties and supersedes all prior or contemporaneous agreements or representations, whether written or oral, concerning its subject matter. This Agreement may not be modified or amended without Licensor’s prior and express written consent, and no other act, document, usage or custom will be deemed to amend or modify this Agreement.
    • You agree that any breach of this Agreement by You would cause irreparable damage to Licensor, and that, in event of such breach, in addition to any and all remedies at law, Licensor will have the right to an injunction, specific performance, or other equitable relief to prevent the continuous violations of the terms of this Agreement.
    • You may not assign, sell, transfer, delegate or otherwise dispose of this Agreement or any rights or obligations under it, whether voluntarily or involuntarily, by operation of law or otherwise, without Licensor’s prior written consent. Any purported assignment, transfer or delegation by You will be null and void. Subject to the foregoing, this Agreement will be binding upon and will inure to the benefit of the parties and their respective successors and assigns. You agree, represent and warrant that You will not export the Software or any underlying technology in contravention of any applicable export laws and regulations applicable in the US or any other relevant country.
    • Notwithstanding anything herein to the contrary, Licensor shall not be liable for any delay or failure in performance caused by an event of Force Majeure or act of God.
    • If any provision of this Agreement is held to be illegal, invalid or otherwise unenforceable, that provision will be enforced to the extent possible or, if incapable of enforcement, deemed to be severed and deleted from this Agreement, and the remainder will continue in full force and effect.
    • Waiver by either party of any default or breach of this Agreement will not waive any other or subsequent default or breach.
    • All notices and communications required or permitted under this Agreement will be in writing and will be sent by any one of the following modes:
      • registered or certified mail, postage prepaid, return receipt requested,
      • facsimile transmission (the “Fax”), with confirmed answer back, or
      • electronic mail, with confirmation of receipt, 

to Licensor or You at the respective addresses we provide to each other or to such other address as Licensor or You may from time to time specify by notice to the other through any of the mode provided in this paragraph. In Licensor’s case, the address is:

PIT Solutions AG
Joweid Zentrum 1
8630 Rüti ZH
Schweiz 

  • This Agreement and all matters arising out of it is governed by the laws in Zürich, Switzerland, without regard to its ‘conflict of law’ principles and parties irrevocably consent to the exclusive jurisdiction of the Court of Zürich, Switzerland. Application of the United Nations Convention on Contracts for the International Sales of Goods is expressly excluded.

 

Implementation Guide

1 Introduction

The purpose of providing an extension for Wallee Payment Solution for SAP Commerce Cloud is to aid the integration of wallee into a SAP Commerce Cloud (previously known as SAP Hybris) implementation. SAP Commerce Cloud Store accelerator will use the newly developed extension to interact with wallee.

The Wallee Payment Solution for SAP Commerce Cloud extension provides a configurable spring component which helps shorten the implementation cycle and reduce system development, testing efforts and maintenance costs for payment integration. The extension package contains most of the backend code needed for creating transactions using wallee into the SAP Commerce Cloud platform. The Merchants can use the wallee Payment Solution for SAP Commerce Cloud extension
with their SAP Commerce Cloud project to integrate wallee.

This document contains information about the functionalities and Payment Integration details of the wallee Payment Solution for SAP Commerce Cloud.

2 Functional Architecture

Figure 2.1: Functional Diagram

3 Technical Overview

The Wallee Payment Solution for SAP Commerce Cloud extension is built on SAP Commerce Cloud (previously known as SAP Hybris) version 1905. Thus, make sure you have the project running with version 1905.

4 Technologies and Tools

The following table summarizes the proposed platform and software recommended for the system hosting. 

Sl. No. Component Description
1 Operating Platform Windows7+ /macOS/Linux
2 Web Server Tomcat
3 Technology  SAP Commerce Cloud/SAP Hybris

Table 1: Application Software

Sl. No Component Description
1 Development Environment Intellij IDE
2 Source Control Git

Table 2: Development Tools

5 Plugin Requirements Scope

The following functionalities are covered as part of the “Wallee Payment Solution for SAP Commerce Cloud Plugin”. In order to create a payment in wallee, there is a choice between Payment Page Integration and iframe Integration. 

5.1 Payment Page Integration

The Payment Page Integration helps in redirecting the customer to the wallee provided payment page where customers can enter the payment details. It allows the processing of all payment methods that are configured with wallee.

  • The process begins with the creation of an order in your shop.
  • Then you have to create Transaction object using the create method on Transaction Service.
  • Use the buildPaymentPageUrl service to create the Payment Page Url.
  • Redirect the customer to the Payment Page Url.
  • When the transaction is processed or failed, the customer will be redirected to the successUrl or failedUrl that was defined when creating the transaction object.
  • Listen to the notification via webhook url, to mark the order in the merchant system as authorized or failed.

5.2 IFrame Integration

The iframe Integration is used in implementing a custom checkout experience by building a payment form in an iframe using wallee provided JavaScript or the lightbox integration in order to achieve a seamless and PCI DSS compliant integration in your checkout. 

  • Create a transaction object with the Transaction service. To create a transaction object, you can provide all the information you have in this state.
  • Once the transaction object is created the possible payment methods can be fetched by using fetchPossiblePaymentmethods on the Transaction Service by providing the transactionId returned by the initial request.
  • To embed the iframe into a website a JavaScript URL has to be fetched. For this the service method buildJavaScriptUrl can be used. The form is then validated.
  • The transaction is confirmed and the application reports the final state of transaction. The iframe is submitted with JavaScript.
  • When the transaction is processed or failed, the customer will be redirected to the successUrl or failedUrl that was defined when creating the transaction object.

5.3 Webhook Configuration

A webhook can be used to notify another application about events. Webhooks are generally triggered by some event for example to notify your application about a status change of an entity. All configuration details can be set inside the space. You can define here the URL as well as chose from the different events for which you want to receive a HTTP call.

  • 5.3.1 URLs
    All URLs you want a webhook delivered to are configured centrally inside our space in wallee. Managing the URLs centrally helps you to easily manage changes to URLs so that you not have to touch every webhook listener configuration.
  • 5.3.2 Webhook Listeners
    A listener can listen on state changes of particular entities. Means when an entity changes into a specified state the URL will be invoked. Only certain entities are enabled to be subscribed by a webhook listener. A Webhook Listener can be created under Webhook Listener Configuration in wallee.
  • 5.3.3 Invocations
    A log of all triggered webhooks can be seen under invocations in webhooks in wallee. By clicking on the invocation, you can see the error in case the webhook failed including the response that we received from your server.

6 Additional Features Considered

  • Plugin must work on most common browsers supported by the shop-system
  • Error Handling
  • Payment methods are configured in account space in wallee.
  • Provide wallee full access to place it on its own portals: Can be provided as ZIP fie.
  • A webhook url is configured in wallee, to get notifications of a successful transaction.

7 Implementation Guide

The purpose of providing an extension for wallee is to aid the integration of wallee paymentservice into a SAP Commerce Cloud implementation. This document describes how to install and configure the extension to work with any SAP Commerce Cloud implementation.

As SAP Commerce Cloud is built on the spring framework this makes it highly customizable and extensible. The extension also utilizes this framework, so it can also be easily extended to add specific behavior if required.

7.1 Prerequisite 

  • Before starting with the integration of the plugin you should sign up with wallee and create a space.
  • This extension is built on SAP Commerce Cloud (previously known as SAP Hybris) version 1905. Thus, make sure you have the project running with version 1905

7.2 Installation and Usage

The plugin is supplied as a zip file. Take the following steps to include the extension into your Hybris application: 

  • Unzip the supplied zip file.
  • Copy the extracted folder to ${HYBRIS_CUSTOM_DIR} of your Hybris installation.
  • Add the Customweb extensions to your localextensions.xml file.
  • Install customwebcheckoutaddon to the storefront in order to make the changes applicable to the storefront.

ant addoninstall -Daddonnames="customwebcheckoutaddon" - DaddonStorefront.yacceleratorstorefront="XXXstorefront"

  • Run the ‘ant clean updatesystem’ command from your ${HYBRIS_PLATFORM_DIR}.
  • Run the hybrisserver.sh/bat to start up the hybris server.
  • Import the project data of the customweb extension from hac.
  • Or skip the steps from 5-7 and do an initialize and then start the server.

7.3 Configuring the Properties

Wallee Payment Solution for SAP Commerce Cloud uses some properties in order to manage the process. Those properties can be seen in the project properties. Some of the main properties are listed below: 

Those properties have names that speak for itself. The transaction create request, build payment page url request etc. are configured here. The spaceId, mac values generated from wallee are also configured here.