Introduction

Welcome to the Intershop PayPal Service Connector. The service connector adds PayPal payment methods to your Intershop Commerce Management installation.

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 PayPal Service Connector 6 is based on the Payment API introduced in Intershop Commerce Management 7.6.1.

Delivery

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

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

The sources for as_responsive_paypal and app_sf_responsive_paypal are available here

...YOUR_REPOSITORY.../releases/com.intershop.public.source/s_payment_paypal/6.1.1/zips/s_payment_paypal-zip-src-6.1.1.zip

Compatibility of Application Types

The PayPal Service Connector can be used for the following application types:

Setup

This section outlines the basic setup and configuration steps, including

• Setting Up the Assembly

• Defining File-Based Configuration

• Deploying the Assembly

Preconditions

• A set up and configured CI environment:

  • See Cookbook - Setup CI Infrastructure (valid to Gradle Tools 2.7) for details

  • See Concept - Continuous Delivery Tools (valid to 7.10) for basic information about Continuous Integration (CI)

• A running Intershop Commerce Management 7.10 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

The package is available via Intershop's public Artifactory.

Setting Up the Assembly

To add the PayPal Service Connector to your Intershop Commerce Management system, you may either:

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

  1. Add the following in the build.gradle file of the assembly:
     build.gradle

     cartridges {    
             def paypalPaymentProvider = [
                 'ac_payment_paypal',
     // these 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',
                 'app_sf_responsive_paypal'
             ]
             include (*(paypalPaymentProvider.collect {"com.intershop.services.payment_paypal:$it"}), in: [development, test, production])
     ...
             order = listFromAssembly(<yourAssembly>) + paypalPaymentProvider
     }

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

     apply plugin: 'static-cartridge'
     apply plugin: 'com.intershop.gradle.isml'
      
     intershop
     {
         displayName = 'Adapter Cartridge for Paypal Payment'
         packages {
             cartridge {
                 srcDir(isml2classMain)
             }
         }
     }
      
     dependencies
     {
         //compile project(':ac_payment_paypal') --> will be replaced by
          compile group: 'com.intershop.services.payment_paypal', name: 'ac_payment_paypal'
     }

  3. Adjust the file as_responsive_paypal/build.gradle in a similar way:
     as_responsive_paypal/build.gradle file

     apply plugin: 'static-cartridge'
      
     intershop
     {
         displayName = 'As_responsive_paypal'
         staticLibs = fileTree(dir: staticCartridgeLibFolder, include: '*.jar')
     }
      
     dependencies {
         //compile project(':ac_payment_paypal') --> will be replaced by
          compile group: 'com.intershop.services.payment_paypal', name: 'ac_payment_paypal'
         compile project(':app_sf_responsive_paypal')
     }

  4. Insert the following lines into the file intershopBuild.version to consume the desired version (e.g. 6.0.4):

     intershopBuild.version

     com.intershop.services.payment_paypal:ac_payment_paypal = 6.0.4

  For details about adding components to an assembly, see Cookbook - Gradle Assembly Tools.
  Or:

• Create a new assembly inheriting from an Intershop Commerce Management system-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 Service Connector.

The PayPal Service Connector requires the following settings:

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

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

Deploying the Assembly

After having created and appropriately having configured 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).

Customization

Changing the Definition of Significant Cart Change

The consequent redirects to PayPal (those after the initial redirect) are done after significant cart changes. What is significant in a cart is defined by the class:

com.intershop.adapter.payment.paypal.internal.basket.BasketHashCodeGenerator

@Named("PayPal_BasketHashCodeGenerator")
public class BasketHashCodeGenerator implements Function<BasketBO, String>

It gets the current BasketBO and creates a hash based on what it considers to be significant.

At some stages of the checkout (payment and review pages) a hash is generated again and if there is a mismatch with the initial hash, the customer will be redirected to PayPal again.

To change the definition of what is significant in a cart:

1. Create your own class YourCustomBasketHashCodeGenerator implementing Function<BasketBO, String>, which generates a hash based on what you consider significant.

2. Bind the new class in your customization Guice module.

   bind(new TypeLiteral<Function<BasketBO, String>>()
   {
   }).annotatedWith(BasketHashCodeGenerator.class.getAnnotation(Named.class))
                .to(YourCustomBasketHashCodeGenerator.class).in(Singleton.class);

Configuration

This section outlines the required post-deployment configuration steps, including:

• Configuration - PayPal Service Connector 6 | Adjusting Firewall Settings

• Configuration - PayPal Service Connector 6 | Applying UI Based Configuration

• Configuration - PayPal Service Connector 6 | Localization

Adjusting Firewall Settings

Adjust your firewall settings according to PayPal's Go Live Checklist.

Applying UI Based Configuration

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

For details about enabling a payment service, see - Recipe: Enable a Payment Service.
The table below lists PayPal-specific settings you can enter at the payment service.

Localization

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

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

For details about localization, see:

• Concept - Localization

• Cookbook - Localization

Feature Overview

Payment Methods

The PayPal Service Connector adds the following payment methods to your Intershop CM system:

Payment Management Options

Order Detail Transmission Options

The PayPal Connector supports different options for transmitting order details to PayPal. To avoid rounding errors it might make sense to adapt this setting within a project in order to make it possible to use PayPal for all use cases.

Explaining Rounding Errors

Rounding errors may occur when transferring the basket to a payment service provider (PSP). When a PSP provides an API to send the different basket totals with 2-digit values (e.g., shipping, taxes, discounts etc.) there is a possibility that summing up everything with 5-digit values will produce a different result than the total amount for authorization. The difference might be as small as a cent, but still enough for the PSP to reject the payment. The reason for rounding issues is price calculation which includes percentage values. For example:

• Converting net prices into gross prices
  This may happen when prices in the Commerce Management application are handled as net and displayed in the storefront as gross.
• Percentage-based discounts

Avoiding Rounding Errors

Since version 4.1 of the PayPal Connector the shop manager has three options to transfer order details (basket transmission) to PayPal.

ICM Option	Possible Rounding Issues	Explanation	Result at PayPal
No Details	no	No details besides the order total appear at PayPal
All Details as Subtotal	no	The connector uses parts of the PayPal API. Order details appear at PayPal as part of the item list.
Details Separated	yes	The connector uses most of the PayPal API. Order details appear at PayPal at dedicated places.

Redirecting on Significant Cart Changes

Once the customer is redirected back from PayPal, the contents of the basket are stored as hash. If significant changes are observed before the order is completed, the customer would be redirected again to PayPal to confirm the payment. Such redirects may occur on the payment and review pages of the checkout process.

• Significant changes are:

  • Product quantity change

  • Adding a product

  • Removing a product

  • Changing the whole or parts of the shipping address:

    • Country

    • City

    • Postal code

    • Address Line 1

• Significant changes are not:

  • Shipping method change

  • Invoice address changes

Data Handling

The following table describes transmitted data by the PayPal Service Connector from ICM to PayPal during the payment process:

Limitations

General Limitations

Matching Price and Taxation Calculation

Please be aware that the PayPal payment cartridge requires a matching price display and tax calculation. 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.

PayPal Express: Customer Redirect to Payment Page Instead of Review Page

A customer being logged in will be redirected to the payment page (not the review page) after confirming payment at PayPal.

However, this does not affect the functionality of the cartridge.

Application Types

The payment methods are available for B2C shops and for those B2B shops in which the order approval is disabled.

PayPal Express for PWA

The express checkout feature is not available for the PWA storefront. The option for express checkout using PayPal will not be available to the user in that case.

PayPal Address Update Not Possible for Orders with Multiple Shipping Buckets

It is possible to enable both "Allow PayPal address update" and "Allow shipping buckets" at the same time. However, if multiple shipping addresses are used for some line items of a basket, it will not be possible to distinguish between those addresses at PayPal. Only one address is set on the PayPal redirect page, which would lead to the different shipping addresses being overwritten with this single address when returning from the PayPal redirect. Therefore, in case of orders with multiple shipping buckets, the address update setting will be disabled at runtime, regardless of the configuration.

PayPal in combination with PWA

Due to a bug in the PWA 3.2 the redirect is not working in combination with that release. The issue is fixed since version 3.3.

Credit Card with IPv6 Addresses

The IP zones feature requires an IPv4 address on the customer's side. In case the customer has an IPv6 address, the payment method Credit Card will not be displayed on the payment page.

Changelog

Version PayPal/6.1.1

• Added localization keys for PayPal Standard- and PayPal Express-specific payment history entries

• Improved handling of PayPal-specific errors within capture functionality

• Fixed issue blocking usage of multiple configurations for same service on the same level

• Fixed bug where payment transaction information could not be sent for products with missing product name

Version PayPal/6.0.4

• Fixed address update handling in case of multiple shipping buckets

• Sensitive banking data are not logged in log files anymore

• Fixed determination of fallback total amount to avoid issues when sending order details to PayPal

Version PayPal/6.0.0

• Support of PayPal Standard within PWA

• Upgrade of PayPal Connector to Tomcat-based ICM (≥7.10.31)

• Removed dependency to responsive cartridge from PayPal

• Improved usage of error log