Document Properties
Kbid
310H97
Last Modified
08-Jan-2024
Added to KB
15-Dec-2023
Public Access
Everyone
Status
Online
Doc Type
Release Notes
Product
  • ICM 11
  • PayPal
Related Product
Public Release Note - PayPal Service Connector 7

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

Version Information and Dependencies

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

Intershop CM

PWA 

PayPal Service Connector

PayPal Core API

PayPal Merchant SDK

11.5.0+

3.3.0+ (checkout with PayPal Express currently excluded)

7.0.0+

1.7.2

2.15.122

The PayPal Service Connector 7 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.

Cartridge

Description

Required

ac_payment_paypal

Includes all base functionality and business logic which is used both in the storefront and the Commerce Management application

Enables PayPal payment connector for the following application type:

  • intershop.REST

This enables you to try out the PayPal Standard Payment Method via REST using the PWA. For trying out the PayPal Express Payment Method, you would need an own client implementation since the PWA does not support it yet.

(tick)

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:

Application Type

Application Type ID

Compatible

Description

Progressive Web App

intershop.REST

(tick)

B2C/B2B via REST

Setup

The customization image for the PayPal Connector is available in Intershop's public repository. In order to add the customization image for the PayPal Connector to your project, it has to be added to the dependencies of your customization. To achieve this, several steps are required:

  1. Register 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, all you need to do is add your project's feature definition cartridge to your development configuration within your main build.gradle.kts. If additional feature cartridges are needed for local development, you can add them here as well.

    intershop_docker {
        // ... other configuration ... 
        developmentConfig {
            appserverAsContainer = true
            cartridgeList.set(setOf("ft_myproject"))
            // alternative scenario using a feature cartridge where paypal isn't included as a runtime dependency:
            // cartridgeList.set(setOf("ft_paypal", "ft_my_other_feature_cartridge_dev"))
            testCartridgeList.set(setOf("ft_mytest"))
        }
    }
  3. Start your application server
    There are several ways to do so. The three main use cases are:

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

    2. Local Docker environment using docker-compose
      Adapt the used compose file in order to tell ICM which cartridges to load. This can be achieved by the environment variable CARTRIDGE_LIST of the app server.

      version: "3.8"
      services:
        customize-paypal:
          image: icm-as-customization-paypal-standard:<TAG>
          volumes:
            - customizations:/customizations
        # ... other services ...
        appserver:
          # ... other appserver settings ...
          container_name: appserver
      
          environment:
            # ... more environment variables ...
            # example cartridge list (assuming the PayPal Connector (ft_paypal) is already defined as dependency). Please adapt to your needs.
            CARTRIDGE_LIST: "ft_myproject"    
      
      # ... more configuration ...
    3. Production environment using Helm charts
      Also in case Helm is used to manage the ICM instances, the cartridge list will need to be adjusted. Please follow Concept - Customization ICM 11 - Deployment to add the PayPal Connector cartridges to that list.

For details on managing the artifacts, see:

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

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.

Name

Description

User Name

Your PayPal seller account's username.

Password

Your PayPal seller account's password.

Signature

Your PayPal seller account's signature.

Environment

Switch between test and live system. Options: live, sandbox, and beta-sandbox.

Logo URL

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

Branding ID

The heading that will be displayed on the PayPal page after redirect. Overrides the logo parameter.

Page Layout

The identifier of the preconfigured page style that will be used for the PayPal page after redirect. Overrides the logo parameter.

Auto Capture

If enabled, the amounts will be automatically captured with the authorization.

Allow PayPal address update

If enabled, the customer can update the shipping address via the PayPal page. This does not apply to orders which contain multiple shipping buckets. For those, the address update is always disabled.

Allow shipping buckets

Enable PayPal for orders being dispatched to multiple addresses or in multiple shipments.

Digital goods

If enabled, the customer can buy Digital Gift Certificate.

PayPal Logo URL

URL of the PayPal logo, which is shown under PayPal payment methods.

Transfer Order Details

Specifies the way to transfer order details to PayPal. Order details include items (prices and quantities), discounts, taxes, handling fees, etc.
See also: Order Detail Transmission Options.

PayPal confirmation button type

Modifies the text value of the PayPal confirmation button.

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:

Feature Overview

Payment Methods

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

Name

Description

Payment Management Options

PayPal Standard

Payment via a PayPal account performing the complete authorization/capturing process

Capture, Cancel, Reduce, Refund

PayPal Express

Payment via a PayPal account using the express checkout button and performing the complete authorization/capturing process

Note

The express checkout feature is not available for the Intershop PWA.

Capture, Cancel, Reduce, Refund

Payment Management Options

Operation

Description

Capture

Request for settling the payment, can be submitted via the Intershop Commerce Management or via the PayPal Web interface

Cancel

Request for abandoning (PayPal: voiding) a payment settlement, can be submitted via the Intershop Commerce Management or via the PayPal Web interface

Reduce

Option to lower the capture amount

Refund

Option to return (parts of) the capture amount

Note

Capture and Cancel operations performed directly in the PayPal Web interface are not synchronized with Intershop Commerce Management. This leads to errors when trying to capture or to cancel those payments in the Intershop Commerce Management.

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 in order 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). When a PSP provides an API to send the different basket totals with 2-digit values (e.g., shipping, taxes, discounts etc.) a possibility occurs that summing up everything with 5-digit values produces a different result to 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 to transfer 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

no details

All Details as Subtotal

no

The connector uses parts of the PayPal API.

Order details appear at PayPal as part of the item list.

item list

Details Separated

yes

The connector uses most of the PayPal API.

Order details appear at PayPal at dedicated places.

separated

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 will 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 change

Tax Changes

It is possible (although very rarely) that the customer is redirected for a second time to PayPal, not influenced by the customer's actions. This may be observed, for example, when a tax is applied to a product in the ICM storefront, but the tax is later changed due to an address change when redirecting back from PayPal. This causes a change of the total amount of the basket, which is considered a significant change, and the customer will be redirected again to PayPal to confirm the payment.

Data Handling

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

Description

PayPal Payment Methods

 PayPal Standard

PayPal Express

Amount

The amount of the transaction

(tick)

(tick)

Currency 

Currency code, e.g., EUR/USD

(tick)

(tick)

Customer details

Customer e-mail, customer first name, last name, country, city, postal code, mobile number

(tick)

(tick)

Shipping Details

Shipping amount, shipping discount

(question)

(question)

Reference (order id)

Order reference generated by merchant

(tick)

(tick)

Address details (street, zip, city, country) 

Invoice and shipping address details provided by the user 

(tick)

(tick)

Description of the items

Product description (optional and configurable in the Intershop Commerce Management)

(question)

(question)

 Symbol

Description

(tick)

Transmitted

(error)

Not Transmitted

(question)

Optional

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

  • Conversion to ICM 11 customization (feature parity to 6.0.4)

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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.