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:

Delivery

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

The image is available in the respective Docker repository intershophub/icm-as-customization-paypal-standard.

Compatibility of Application Types

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

Setup

The customization image for the PayPal Connector is available in Intershop's public repository.

Helm Declaration of Extension for Deployment

Add customization to helm values:

• Declaration customization image

• Add feature cartridge ft_paypal to cartridge list (See Concept - Customization - Deployment - ICM 11+)

icm-as:
    customizations:
        paypal_standard:
            repository: intershophub/icm-as-customization-paypal-standard:<TAG>
...
    environment:
        CARTRIDGE_LIST: "ft_icm_as ft_paypal"

Using Docker Compose to Start the Server with the Extension Image

Before starting ICM with the PayPal extension, ensure that all required services, the MSSQL database, and the web server are running.

Modify the compose file to specify which cartridges the ICM should load. This is done by setting the CARTRIDGE_LIST environment variable on the application server:

version: "3.8"
services:
    customize-paypal-standard:
        image: icm-as-customization-paypal-standard:<TAG>
        volumes:
            - customizations:/customizations
...
    appserver:
        depends_on:
        - customize-paypal-standard
...
        environment:
            # ... more environment variables ...
            # Example cartridge list. Please adapt to your requirements.
            CARTRIDGE_LIST: "ft_icm_as ft_paypal"
...

When the application server is started, a DBPreparation process will run to configure the PayPal payment services. Once this process is complete, you can log in to the back office. Under Services, the PayPal payment services should be available for use.

To use the PayPal payment services, configure the PayPal payment service with the required credentials, PSP communication URLs, and other configuration parameters.

Customize the Connector

To customize the PayPal Connector, it is necessary to create a customization project for the payment connector.

To add the customization image for the PayPal Connector to your project, add it to the dependencies of your customization. To achieve this, perform the following steps:

1. Register the customization image in your main build.gradle.kts:

   val icmDockerRegistry = "docker.tools.intershop.com/icm/intershophub"
   // specified in gradle.properties
   val paypalConnectorVersion: String by project
   
   intershop {
       projectConfig {
           modules {
               // ... other modules ...
   
               register("paypal-standard") {
                   dependency.set("com.intershop.services.payment_paypal:paypal-standard:${paypalConnectorVersion}")
                   image.set("${icmDockerRegistry}/icm-as-customization-paypal-standard:${paypalConnectorVersion}")
                   testImage.set("${icmDockerRegistry}/icm-as-customization-paypal-standard:${paypalConnectorVersion}")
               }
           }
       }
   }
   
   subprojects {
       // ... other settings ...
    
       plugins.withType<JavaPlugin> {
           dependencies {
               // ... other dependencies ...
    
               cartridge(platform("com.intershop.services.payment_paypal:versions:${paypalConnectorVersion}"))
               implementation(platform("com.intershop.services.payment_paypal:versions:${paypalConnectorVersion}"))
            }
       }
   }

2. Add dependencies to the PayPal feature to your project's feature definition (e.g., ft_myproject/build.gradle.kts)

   dependencies {
       // base on ICM AS
       cartridgeRuntime ("com.intershop.icm:ft_icm_as")
       
       // ... more dependencies ...
   
       // PayPal Connector
       cartridgeRuntime ("com.intershop.services.payment_paypal:ft_paypal")
   }

   To include the PayPal feature, add your project's feature definition cartridge to your development configuration within your main build.gradle.kts. If you need additional feature cartridges for local development, you can add them here as well.

   intershop_docker {
       // ... other configuration ... 
       developmentConfig {
           appserverAsContainer = true
           cartridgeList.set(setOf("ft_myproject"))
           testCartridgeList.set(setOf("ft_mytest"))
       }
   }

3. Define paypalConnectorVersion in your gradle.properties:

   ...
   paypalConnectorVersion = <TAG>
   ...

4. Start your application server in development mode:

   • Use Gradle to manage the server instance by using the command gradlew startAS

   • Run gradlew tasks to see available tasks or check for further options.

For details on managing the artifacts, see:

• Concept - Customization - Development - ICM 11+

• Concept - Customization - Deployment - ICM 11+

Customization

Changing the Definition of Significant Cart Change

The subsequent redirects to PayPal (those after the initial redirect) occur 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 process (payment and review pages), another hash is generated, 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> that 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 8 | Applying UI Based Configuration

• Configuration - PayPal Service Connector 8 | Localization

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 Cookbook - Payment | 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_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 Commerce Management system:

Payment Management Options

Order Detail Transmission Options

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

Explaining Rounding Errors

Rounding errors are related to basket transmission to a payment service provider (PSP). If 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 the sum of 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 back office 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 for submitting order details (basket transmission) to PayPal.

Back Office 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 a hash. If significant changes are detected before the order is completed, the customer will be redirected back to PayPal to confirm the payment. Such redirects may occur at 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 change

Data Handling

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

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 either both be set to "gross" or both be 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.

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/8.0.0

• Migrated the connector to an ICM 12 customization (JDK 21, jakarta packaging)