Public Release Note - PayPal PLUS Service Connector 6

1 Introduction

Welcome to the Intershop PayPal PLUS Connector. The service connector adds PayPal PLUS to your Intershop installation.

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

1.1 References

1.2 Version Information and Dependencies

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

Intershop Commerce ManagementPayPal PLUS Connector
7.10.31.x + (Tomcat 9)6.0.0

PayPal Plus Connector version 6.0.0 features the same functionality as PayPal Plus Connector 5.0.5 to facilitate migration from ICM 7.10.30 - to 7.10.31+.


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

CartridgeDescriptionRequired
ac_payment_paypal_plusIncludes all base functionality and business logic which is used both in the storefront and the Commerce Management application.(tick)
ac_payment_paypal_plus_boIncludes non-standard functionality which is available solely in the Commerce Management application, e.g., the initialization of the payment connector in the course of which also the PayPal experience profile is being created.

(tick)

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.

(error)

ac_payment_paypal_plus_responsive_sf

Includes some additional functionality which is relevant only for the responsive storefront reference application,e.g., 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 the project and has to be referenced in the build.gradle file with the customized naming again.

(error)

The PayPal PLUS Service Connector 6.+ is based on the Payment API introduced in Intershop 7.6.

The sources for as_responsive_paypal_plus and ac_payment_paypal_plus_responsive_sf can be downloaded here (use your repository login and password for authorization):

https://repository.intershop.de//releases/com.intershop.public.source/s_payment_paypal_plus/6.0.0/zips/s_payment_paypal_plus-zip-src-6.0.0.zip

1.3 Supported Application Types

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

Application TypeApplication Type IDDescription
B2C WebShop

intershop.B2CResponsive

Business to consumer channel

2 Feature Overview

2.1 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:

OperationDescription
CaptureA capture is automatically performed after a redirect back to the merchant site. A workflow that performs authorization and capture separately is currently not supported.
RefundOption to return (parts of) the captured amount. Also supports multiple refunds.

Note

Operations that are performed in the PayPal Web interface may be synchronized with Intershop Commerce Management using webhooks.

2.2 Webhooks

2.2.1 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:

Event TypeDescription
PAYMENT.SALE.COMPLETEDThis event is triggered when a sale is completed.
PAYMENT.SALE.DENIEDThis event is triggered when the sale status changes from pending to denied.
PAYMENT.SALE.PENDINGThis event is triggered when the sale status changes to pending.
PAYMENT.SALE.REFUNDEDThis event is triggered when the sale is refunded by the merchant.
PAYMENT.SALE.REVERSEDThis event is triggered when the sale is reversed by PayPal.

2.2.2 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:

ac_payment_paypal_plus.properties
intershop.payment.PAYPAL_PLUS.SkipWebhookSignatureVerification = false

Note

For security reasons you should switch off the validation only for testing purposes.

2.2.3 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.

2.3 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.

3 Setup

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

Note

Managing and deploying the PayPal PLUS Service Connector requires a continuous integration (CI) environment being set up and configured as described in Cookbook - Setup CI Infrastructure.

3.1 Precondition

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

3.2 Setting Up the Assembly

To add the PayPal Service Connector into your ICM system, there are two options.

3.2.1 Option 1

  • Incorporate the cartridge into an already existing assembly. To do so, follow these steps:

  1. In the build.gradle file of the assembly, add:

    build.gradle
    …..
     
    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'
    }
    
    
    

    Note

    The assembly in which the PayPal PLUS Connector works should exclude the jaxb-impl artifact. Therefore, the closure configurations.all has been added in the code example above. This is required due to version conflicts with the Jersey client. The Jersey client is used for consuming RESTful services provided by PayPal.

  2. Adapt the ac_payment_paypal_plus_responsive_sf/build.gradle file in the following way:

    ac_payment_paypal_plus_responsive_sf/build.gradle
    apply plugin: 'static-cartridge'
    apply plugin: 'com.intershop.gradle.isml'
    
    intershop 
    {
    	displayName = 'Adapter -Payment_paypal_plus_responsive_sf '
    	packages {
            cartridge {
                srcDir(isml2classMain)
            }
        }
    }
    
    
    dependencies 
    {
    //   compile project(':ac_payment_paypal_plus') --> will be replaced by
         compile group: 'com.intershop.services.payment_paypal_plus', name: 'ac_payment_paypal_plus'
    }
    
  3. Insert the following lines into file intershopbuild.version:

    intershopbuild.version
    com.intershop.services.payment_paypal_plus:ac_payment_paypal_plus = 6.0.0
    com.intershop.services.payment_paypal_plus:ac_payment_paypal_plus_bo = 6.0.0
    
    

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

3.2.2 Option 2

For details about managing assembly artifacts, see:

3.3 Defining File-Based Configurations

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:

PropertyDescriptionValue
intershop.payment.PAYPAL_PLUS.currencies
Defines which currencies are configurable for PayPal PLUS. Common setting for all payment service connectors.comma separated list of currencies, e.g., EUR, USD
intershop.payment.PAYPAL_PLUS.PaymentWallTTL
The time to live of the payment wall in minutes, i.e., how much minutes the wall is considered valid in the merchant site after being visualized at the shop. Once the payment wall expires, the user is being redirected to the page where the wall is visualized.number, e.g., 120
intershop.payment.PAYPAL_PLUS.SkipWebhookSignatureVerification

The recommended behavior is to verify the events (i.e. value = false).

true or false

This setting may be overridden within <IS_SHARE>/system/config/cartridges/ac_payment_paypal_plus.properties, see Recipe: Change Deployed File Content With Filters.

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

3.4 Deploying the 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).

Note

The PayPal PLUS Service Connector requires additional post-deployment configuration steps. For details, refer to Configuration.

4 Configuration

4.1 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:

4.2 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.

NameDescription
Client IDThe client ID, provided by PayPal.
SecretThe secret key, provided by PayPal.
EnvironmentSwitch between test (sandbox) and live system. Options: Live and Test.
Webhook ID

The ID of the webhook that is used to accept callbacks from PayPal. Maintained in the PayPal account.
When the webhook URL is entered in the PayPal UI and the supported events are selected, PayPal assigns a webhook ID to the configuration.
This ID is essential for the webhook validation. If the validation is switched off, the webhook ID is not required.

Proxy hostThe proxy host
Proxy portThe proxy port
Proxy user nameThe proxy user (if applicable)
Proxy passwordThe proxy password (if applicable)
Logo Image

The URL of the logo that will be displayed on the PayPal page after redirect.

Allowed values: *.gif, *.jpg, or *.png. Limit the image to being 190 pixels wide by 60 pixels high.
PayPal crops images that are larger. PayPal places the image at the top of the cart review area.
(warning) PayPal recommends that the image is stored on a secure (HTTPS) server. Otherwise, web browsers display a message that checkout pages contain non-secure items.
Character length and limit: 127 single-byte alphanumeric characters.

Brand Name

The brand of the shop, shown on the PayPal hosted pages.

A label that overrides the business name in the PayPal account on the PayPal pages. Character length and limitations: 127 single-byte alphanumeric characters.

LocationDetermines the locale-specific variant of the PayPal hosted pages.

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

Note

Proxy support is available for intercepting proxies. The usage of such proxies is not recommended because the idea of SSL is to make sure that there are no proxies between the merchant and PayPal. If you use such proxy, make sure that the certificate of the proxy is trusted by the JVM on which the app server runs. Proxy usage is highly discouraged.

4.3 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

Note

The connector cannot be guaranteed to work correctly without experience profile. Initializing the connector is required.

4.4 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:

5 Limitations

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

LimitationDescription
Multiple shippingMultiple shipping is not supported.
Limitations in the hosted pages

The change of the shipping address in the hosted pages of PayPal is not supported.

Writing notes to the merchant is also not supported.

The restrictions are enforced by an experience profile.

Payment costsPayment costs are not supported because the payment wall is displayed before a payment method is selected.

Matching price and taxation calculation

A matching price display and tax calculation is required.
That is, the price type and the price display must be either both set to "gross" or both set to "net", and a corresponding taxation service must be enabled.

Baskets with zero subtotals

Baskets with subtotal of zero are not supported by PayPal.
Thus, a basket which has a product and a promotion that covers the amount of the product cannot be processed even if the basket includes a handling fee that is to be paid.
US address validationPayPal supports validation of US shipping addresses. However, the PayPal PLUS Connector 6 does not support validation of such addresses, i.e. invalid US shipping addresses will not be recognized.
Pending transactions

In certain rare situations PayPal may decide to mark a transaction as "pending".
The merchant may, for example, require to review all payments before capturing. Later a transaction may be captured. This scenario is supported only via webhooks.

The calculations which are performed during the "normal" workflow of the checkout (e.g., recalculating a promotion budget) will not be triggered by the webhook currently.

Digital goodsBuying digital goods (e.g., gift certificates) is not supported due to the lack of physical address.
PWA REST storefrontPWA REST storefront is not yet supported. PayPal PLUS only works with responsive-based storefront.

6 Changelog

6.1 Version PAYPALPLUS/6.0.0

  • User Story 64006: Upgrade PayPal PLUS Connector to Tomcat-9-based ICM (≥7.10.31)

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets