Introduction

This release note provides important product information, including version information and dependencies. It also outlines the basic setup and configuration steps.

References

• Concept - Payment Framework
• Cookbook - Payment
• Concept - Intershop Reference Payment Services

Version Information and Dependencies

This delivery and the accompanying documentation are valid for the following combinations of software versions:

The next table provides information about the cartridges included in the package. Not all of these cartridges are required.

Cartridge	Description	Required
ac_payment_paypal_plus	Includes all base functionality and business logic which is used both in the storefront and the Commerce Management application
ac_payment_paypal_plus_bo	Includes non-standard functionality which is available solely in the Commerce Management application E.g., this is the initialization of the payment connector which process also creates PayPal experience profile
as_responsive_paypal_plus	Enables PayPal PLUS payment connector for the following application types: intershop.B2CResponsive The cartridge is optional, can be downloaded separately from Intershop Product Calendar and may be included if the project uses the responsive starter store. Unzip the file to your multi-project folder next to your responsive source files. It can be skipped if the custom project does not support these application types or PayPal PLUS is not required in these application types.
ac_payment_paypal_plus_responsive_sf	Includes some additional functionality which is relevant only for the responsive storefront reference application. E.g., this is the detection of basket changes which require re-rendering of the payment wall. The cartridge is optional, can be downloaded separately from Intershop Product Calendar and may be included in case that the project is based on the responsive storefront reference application. Unzip the file to your multi-project folder next to your responsive source files. The referenced cartridge app_sf_responsive may be renamed in project and has to be referenced in the build.gradle file with the customized naming again.

The PayPal PLUS Service Connector 5.+ is based on the Payment API 2.8.

The sources for as_responsive_paypal_plus and ac_payment_paypal_plus_responsive_sf are available here

...YOUR_REPOSITORY.../releases/com.intershop.public.source/s_payment_paypal_plus/5.0.5/zips/s_payment_paypal_plus-zip-src-5.0.5.zip

Supported Application Types

The PayPal PLUS Connector may be used out of the box for the following application types:

Feature Overview

Payment Management Options

The PayPal PLUS payment connector offers the display of a payment wall in which the storefront users (customers) may choose between several payment methods:

• Payment with PayPal account;
• Payment with credit card;
• Payment with debit card;
• Pay upon invoice - available on sandbox (German business accounts and EUR currency only) and depending on the contract - on live systems;

More methods may be added in the future. Some may be excluded depending on the contract between PayPal and the merchant. The next figure shows the display of the payment wall in the third step of the checkout.

When the users make their choice, they are redirected after checkout to a PayPal hosted page where the actual payment takes place. Then the users are redirected back to the webshop site of the merchant. No sensitive information is stored by the merchant.

The connector supports the following operations:

Webhooks

General Information

Webhooks are user-defined HTTP callbacks that receive events for the subscribed event types. The main purpose of these events is the synchronization of the payment status between Intershop Commerce Management and PayPal. This way, e.g., a refund can be triggered from both, the Intershop Commerce Management application and the merchant UI hosted by PayPal. For detailed information about webhooks, see the PayPal documentation at PayPal Webhooks Overview.

Currently Intershop Commerce Management supports the following webhook event types:

Webhook Validation

The webhook payload is digitally signed by PayPal. If the signature cannot be verified, the system will discard the event. Webhook validation can be switched on/off by a file-based configuration property:

intershop.payment.PAYPAL_PLUS.SkipWebhookSignatureVerification = false

Receiving a Webhook

The following Intershop Commerce Management endpoint listens for webhook events:

http://<host>:<port>/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/PayPalPlus-Webhook

Here host and port are the host and the port where the Intershop Commerce Management system is available. When a webhook event is received, Intershop Commerce Management will synchronize a transaction with PayPal. Transactions can have different statuses in both systems because the same operations (e.g., a refund) may be performed both in the Intershop Commerce Management back office and also in the merchant UI at PayPal.

Experience Profiles

An experience profile defines certain behavior and branding of the PayPal hosted payment pages. Currently the following branding settings are supported:

• Logo image - a small logo that can be shown at the hosted pages
• Brand name - a short text that is the name of the merchant shop

The following behavior is enforced by the payment connector when an experience profile is created:

• The shipping address cannot be changed on PayPal hosted pages
• Notes cannot be written on PayPal hosted pages

Only one experience profile is created per channel. Multiple experience profiles may exist for single API keys. Experience profiles are created or updated implicitly when the connector is initialized.

Setup

This section outlines the basic setup and configuration steps, including:

Precondition

The package is available via Intershop's public Artifactory servers.

• A setup and a configured CI environment, see:
  • Cookbook - Setup CI Infrastructure
  • Concept - Continuous Delivery Tools (valid to 7.10)
• A running ICM 7.9 installation that matches the system requirements
• Knowledge of how to add the delivered artifacts to the continuous integration environment
• Knowledge of how to deploy to a test or production environment

Set Up the Assembly

To add the PayPal Service Connector into your ICM system, you may either:

• Incorporate the cartridge into an already existing assembly.

In the build.gradle file of the assembly add:

…..
 
cartridges {
        def storefrontCartridges = [
            'app_sf_responsive',
            'app_sf_responsive_cm',
            'app_sf_responsive_b2c',
            'app_sf_responsive_smb',
            'as_responsive',
            'app_sf_responsive_b2b',
            'app_sf_responsive_costcenter',
            'as_responsive_b2b',
// this are the two cartridges, which we delivered in source code and you have to add these files to your responsive source project
                 'as_responsive_paypal_plus',
                 'ac_payment_paypal_plus_responsive_sf'
           ]
        include(*(storefrontCartridges.collect { project(":$it") }), in:[development, test, production])
  
…..
 
        def paypalPlusPaymentProvider = [
            'ac_payment_paypal_plus', 
            'ac_payment_paypal_plus_bo'
        ]
        include (*(paypalPlusPaymentProvider.collect {"com.intershop.services.payment_paypal_plus:$it"}), in: [development, test, production])    
  
        order = listFromAssembly(baseAssembly) + paypalPlusPaymentProvider 
    }
...
assemblyBuild {
    database {
        inherit(<yourAssembly>)
        initCartridges = []
    }
}
...
configurations.all {
    exclude group: 'com.sun.xml.bind', module: 'jaxb-impl'
}

Furthermore you have to adapt the ac_payment_paypal_plus_responsive_sf/build.gradle file in the following way:

apply plugin: 'static-cartridge'
 
intershop
{
       displayName = 'Adapter -Payment_paypal_plus_responsive_sf '
}
 
 
dependencies
{
//   compile project(':ac_payment_paypal_plus') --> will be replaced by
     compile group: 'com.intershop.services.payment_paypal_plus', name: 'ac_payment_paypal_plus'

   compile group: 'com.intershop.platform', name: 'businessobject'
   compile group: 'com.intershop.platform', name: 'core'
   compile group: 'com.intershop.platform', name: 'bc_address'
   compile group: 'com.intershop.platform', name: 'isml'
   compile group: 'com.intershop.platform', name: 'servletengine'
  
   compile group: 'com.intershop.business', name: 'bc_basket'
   compile group: 'com.intershop.business', name: 'bc_payment'
 
// compile group: 'com.intershop.responsive', name: 'app_sf_responsive' --> will be replaced by
   compile project(':app_sf_responsive')
  
   compile 'javax.servlet:javax.servlet-api'
   compile 'org.slf4j:slf4j-api'
   compile 'org.apache.tomcat:tomcat-el-api'
}

Now you have to insert the following lines into file: „intershopbuild.version“

com.intershop.services.payment_paypal_plus:ac_payment_paypal_plus = 5.0.5
com.intershop.services.payment_paypal_plus:ac_payment_paypal_plus_bo = 5.0.5

For details about adding components to an assembly, see Recipe: Add Cartridges to an Assembly.

Or:

• Create a new assembly inheriting from an Intershop CM based assembly. For details about creating a new assembly, see Recipe: Create a New Assembly Inheriting From an Existing Assembly.

For details about managing assembly artifacts, see:

• Concept - Gradle Assembly Tools
• Reference - Gradle Assembly Tools
• Cookbook - Gradle Assembly Tools

Defining File-Based Configuration

Before deploying the new assembly to a test or production environment, you may have to adjust some file-based configurations required by the PayPal PLUS Service Connector.

The PayPal PLUS Service Connector requires the following settings:

intershop.payment.PAYPAL_PLUS.currencies

intershop.payment.PAYPAL_PLUS.PaymentWallTTL

intershop.payment.PAYPAL_PLUS.SkipWebhookSignatureVerification

According to Recipe: Change Deployed File Content With Filters this setting may be overridden within <IS_SHARE>/system/config/cartridges/ac_payment_paypal_plus.properties.

For details about adding new configuration files, see Recipe: Deploy Custom Files.

Deploying Assembly

After creating and appropriately configuring the assembly, you must deploy it to the intended target environment.

For details about deploying an assembly, see Recipe: Run the Deployment (Initial Installation / Upgrade / Downgrade).

Configuration

Enabling Within the Operations Back Office

Within the Operations back office, the managed service corresponding to the PayPal PLUS Connector is by default named Securely processed by PayPal. The service has to be enabled for the Sales Organization in which the connector will be used. This is shown in the screenshot:

Apply UI-Based Configuration

The PayPal PLUS Connector requires some post-deployment configurations in Organization Management and Commerce Management.

For details about enabling a payment service, see - Recipe: Enable a Payment Service .

The table below lists PayPal PLUS-specific settings to be configured at the payment service.

The logo image and brand name are part of the experience profile of the merchant.

Connector Initialization

Once the connector is configured, it should be initialized in the channel back office. To do so, use the ad-hoc Initialize button. The button is available in the Preferences tab, as shown in the the screenshot below.

Two things happen when the button is clicked:

• The connectivity with PayPal is confirmed
• An experience profile is created or updated

Localization

The PayPal PLUS Connector provides English and German localization files for the payment-specific input field labels, error messages, etc.

You can find the existing localization files here: <IS.INSTANCE.SHARE>/system/cartridges/ac_payment_paypal_plus/release/localizations and <IS.INSTANCE.SHARE>/system/cartridges/ac_payment_paypal_plus_bo/release/localizations

For details about localization, see:

• Concept - Localization
• Cookbook - Localization

Limitations

This following table summarizes known limitations with this implementation of the connector.

Changelog

Version PAYPALPLUS/5.0.5

• Fix: PAYPALPLUS-162 - wrong duplicate path in paypalplus connector wrong duplicate path in paypalplus connector
• Fix: PAYPALPLUS-160 - Deprecated syntax in logback configuration Deprecated syntax in logback configuration

Version PAYPALPLUS/5.0.4

• Fix: PAYPALPLUS-96 - name of extension adjusted to fulfill naming convention
• Fix: PAYPALPLUS-155 - display of duplicate error message removed
• Fix: PAYPALPLUS-156 - removed code changes made to solve PAYPALPLUS-143
• Fix: PAYPALPLUS-157 - in case of an invalid or not available PayPal Plus connection the connector is treated as "not applicable" and not presented to the customer
• Fix: PAYPALPLUS-143 - orders with invalid or not available paypal plus connection can be placed - Orders with invalid or not available PayPal Plus connection cannot be placed anymore.

Version PAYPALPLUS/5.0.0

• Fix: PAYPALPLUS-139 - Order number of ICM will be transferred to PayPal, so customers are able to search the order in PayPal system (field: Invoice ID). 
• Fix: PAYPALPLUS-138 - PayPal PLUS connector requires jersey client library version 2.