Introduction

Welcome to the Intershop PayPal Complete Payments Service Connector (PPCP Connector) version 2.
This connector is a complete rewrite of the previous “PayPal Service Connector” and now integrates with PayPal using the PayPal Orders REST API v2 and the Partner Referrals API v2 for merchant onboarding (Integrated Sign Up [ISU]). It replaces the PayPal Service Connector 8, which uses the PayPal Classic API for communication with the provider, and aligns with current PayPal platform capabilities.

The connector implements Intershop’s Payment Framework and exposes modern PayPal payment and onboarding features for Intershop Commerce Management (ICM) projects.

This release note summarizes the version scope, dependencies, setup, customization options, configuration steps, capabilities, and known limitations.

References

• Concept - Payment Framework

• Cookbook - Payment

• Concept - Reference Payment Services

• Public Release Note - PayPal Service Connector 8

• PayPal REST APIs

Version Information and Dependencies

Used PayPal REST APIs:

• Orders v2

• Partner Referrals v1 & v2

• Webhooks Management v1

Delivery

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

Compatibility of Application Types

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

Setup

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

Helm Declaration of Extension for Deployment

Add the customization according to standard Intershop Helm deployment patterns:

1. Add the customization image reference.

2. Append the feature cartridge ft_ppcp to CARTRIDGE_LIST (see Concept - Customization - Deployment - ICM 11+).

3. Provide required environment variables.

Example (simplified excerpt):

icm-as:
  customizations:
    paypal-complete-payments:
      repository: intershophub/icm-as-customization-paypal-complete-payments:<TAG>
...      
  environment:
    CARTRIDGE_LIST: "ft_icm_as ft_ppcp"
    # PayPal configuration (examples for sandbox - replace "sandbox" by "production" for a live environment)
    INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_SANDBOX_CLIENTID: "<sandbox-client-id>"
    INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_SANDBOX_SECRET: "<sandbox-secret>"
    INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_SANDBOX_WEBHOOKID: "<pre-registered-webhook-id>"
    INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_SANDBOX_ATTRIBUTIONID: "<intershop-bn-code>"
    INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_SANDBOX_PARTNERMERCHANTID: "<intershop-partner-id>"

Using Docker Compose to Start the Server with the Extension Image

1. Ensure DB and required infrastructure is running.

2. Mount customization layer or reference the combined image.

3. Extend CARTRIDGE_LIST to include ft_ppcp.

4. Provide PayPal Complete Payments related environment variables in appserver service.

After startup, the database preparation registers the new payment service(s). Once this process is complete, you can log in to the Intershop Commerce Management and find the PayPal payment services available for use under Services.

Customize the Connector

In case it is needed to customize the PayPal Complete Payments Connector, you need to create a customization project for the payment connector.

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

1. Add the dependency in your main build.gradle.kts (example snippet):

   val ppcpConnectorVersion: String by project
   
   intershop {
     projectConfig {
       modules {
         register("paypal-complete-payments") {
           dependency.set("com.intershop.services.payment_paypal_checkout:paypal-complete-payments:$ppcpConnectorVersion")
           image.set("$icmDockerRegistry/icm-as-customization-paypal-complete-payments:$ppcpConnectorVersion")
           testImage.set("$icmDockerRegistry/icm-as-customization-paypal-complete-payments:$ppcpConnectorVersion")
         }
       }
     }
   }
   
   subprojects {
     plugins.withType<JavaPlugin> {
       dependencies {
         cartridge(platform("com.intershop.services.payment_paypal_checkout:versions:$ppcpConnectorVersion"))
         implementation(platform("com.intershop.services.payment_paypal_checkout:versions:$ppcpConnectorVersion"))
       }
     }
   }

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

   dependencies {
     cartridgeRuntime("com.intershop.icm:ft_icm_as")
     cartridgeRuntime("com.intershop.services.payment_paypal_checkout:ft_ppcp")
   }

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_ppcp"))
    }
}

3. Define ppcpConnectorVersion in gradle.properties.

   ...
   ppcpConnectorVersion = <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+

Configuration

This section outlines the required post-deployment configuration steps.

In general, it is recommended to configure the PayPal Complete Payments service(s) on channel level.

Applying UI-Based Configuration

The UI-based configuration is divided into two sections. One is common for all PayPal Complete Payments services configured for the channel and available in the Preferences. The PayPal Complete Payments section is available as soon as the connector is deployed, even if no service is configured yet.

In the general preferences for the PayPal Complete Payments, you can toggle the visibility of the Pay Later feature provided by PayPal.

Enabling and Configuring a Payment Service

See Cookbook - Payment | Recipe: Enable a Payment Service for detailed instructions on enabling and configuring a payment service.

Onboarding and Service Configuration

In contrast to other managed services, the configuration cannot be completed within a single creation wizard run-through.

Follow these steps:

1. At first, create the managed service and complete the initial configuration in the Services tab.

   

2. Reopen the newly created service and perform the onboarding with PayPal. To do so, go to the Integration tab and click the button Connect a PayPal Account.
   

   

3. This initiates the onboarding process and you are redirected to PayPal.
   

   

4. Finally, you are redirected and will be able to configure the details of the service. Details about the connected account are shown at the bottom of the page as reference.

The table below lists PayPal-specific settings you can enter at the payment service.

Localization

You can find the existing localization files here: <IS_SHARE>/system/cartridges/ac_payment_paypal_checkout/release/localizations

For details about localization, see:

• Concept - Localization

• Cookbook - Localization

Feature Overview

Payment Methods

Payment Management Options

Order Detail Transmission Options

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

The e-commerce manager has three options for submitting order details (basket transmission) to PayPal.

Redirecting on Significant Cart Changes

If a basket mutates (pricing, items, shipping) after initial PayPal approval, a reinitiation flow ensures that PayPal has accurate amounts.

Onboarding (Integrated Sign Up / ISU)

The connector supports merchant onboarding via Partner Referrals API v2. To connect the service to a PayPal account, merchants follow the steps described in Onboarding and Service Configuration.

Webhooks

In order to react to permission changes on PayPal side, ICM listens to the following events:

Data Handling

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

No raw payment instrument credentials (funding sources) are stored.

Limitations

Application Types

Only REST (PWA storefront) is officially supported by the 2.1.0 release.

Credit Card Support

Direct credit card fields are not part of this connector; only PayPal Wallet flows are included in 2.1.0.

PayPal Messages on Homepage

The states of configuration options for displaying the messaging feature are transferred to the REST client. The current PWA version does not support messages on the homepage.

Digital Goods Support

The connector supports paying baskets with digital goods. It is not completely supported by the PWA.

Migration Guides

There is no direct migration path from PayPal (Standard) Service Connector 8 to PayPal Complete Payments Connector 2. They do not share sources or configuration, so they can be deployed on the same environment. However, avoid having both connectors active for customers to prevent confusion.

Recommended steps for switching integrations:

1. Deploy to non-production.

2. Enable ft_ppcp alongside ft_paypal.

3. Re-onboard the merchant used in the legacy integration.

4. Validate payment lifecycle scenarios (authorize/capture/refund).

5. Disable the payment methods provided by the legacy PayPal integration for the intershop.REST application.

This way, no new orders can be created with the legacy PayPal payment methods, while the management options continue to remain available.

Changelog

Version 2.1.0

• Complete rewrite using PayPal’s recent REST APIs for orders, payment, and integrated sign-up.