Introduction

Welcome to version 3 of the Intershop PayPal Complete Payments Service Connector.

This major version introduces a modernized connector generation based on the PayPal REST APIs for payment operations and merchant onboarding. It is explicitly designed for use within the PayPal Partner Program and provided by Intershop in the role of a PayPal technology partner, enabling merchants to onboard and use PayPal via a partner‑managed setup flow.

As the successor to the former PayPal Service Connector 8, this connector establishes a future‑ready foundation by replacing the legacy PayPal Classic API and aligning the integration with PayPal’s current platform strategy.

The PPCP Connector implements Intershop’s Payment Framework and exposes the latest PayPal payment, onboarding, and account‑management capabilities for Intershop Commerce Management projects.
This release note provides an overview of the connector’s scope, dependencies, configuration and customization options, supported features, and known limitations.

References

• Concept - Payment Framework

• Cookbook - Payment

• Concept - Reference Payment Services

• Public Release Note - PayPal Service Connector 8

• PayPal REST APIs

Glossary

This glossary describes the terms used in this document:

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 PayPal Complete Payments Connector is deployed using its dedicated customization image and the feature cartridge ft_ppcp. Compared to previous connector generations, setup is aligned with the connector’s shared configuration model for onboarding and runtime operation.

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>"

Secure Handling of PayPal Credentials (Production Environments)

For managed environments, Intershop recommends storing PayPal credentials in Azure Key Vault and synchronizing them to Kubernetes using the External Secrets Operator.

This setup provides:

• No credentials committed to Git repositories

• Centralized, environment-specific secret management

• Automatic synchronization and refresh

• Support for secret rotation without changing Helm values

For background information about the secret management architecture, see Guide - Secret Store Process.

SANDBOX and PRODUCTION Credential Sets

The PPCP Connector supports two credential sets:

• SANDBOX credentials

• PRODUCTION credentials

The active mode (SANDBOX or PRODUCTION) is configured at runtime in the ICM back office within the PayPal Common Configuration service . Depending on this setting, the connector reads the corresponding environment variables.

Therefore, the required credentials must be available in the respective Kubernetes environment.

In UAT and Production environments, providing both credential sets allows switching between SANDBOX and PRODUCTION without redeployment.

For secure handling of PayPal credentials, you need to:

1. Store credentials in Azure Key Vault

2. Synchronize secrets to Kubernetes

3. Inject secrets via Helm

These steps are described in more detail below.

Storing Credentials in Azure Key Vault

Create the required secrets in the environment-specific Azure Key Vault.

Required SANDBOX Secrets:

• ppcp-sandbox-clientid

• ppcp-sandbox-secret

• ppcp-sandbox-webhookid

• ppcp-sandbox-attributionid

• ppcp-sandbox-partnermerchantid

Required PRODUCTION Secrets:

• ppcp-production-clientid

• ppcp-production-secret

• ppcp-production-webhookid

• ppcp-production-attributionid

• ppcp-production-partnermerchantid

The secret names must match the remoteRef.key values used in the ExternalSecret configuration.

Synchronizing Secrets to Kubernetes

Create an ExternalSecret resource in your environment repository (e.g., environments/<env>/icm/secret-store.yaml) and add this resource to your kustomization.yaml.

Example (secret-store.yaml):

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: ppcp-secret
  namespace: ${namespace}
spec:
  refreshInterval: 15m
  secretStoreRef:
    name: ${secret_store_eso_sest_name}
    kind: SecretStore
  target:
    name: ppcp-secret
    creationPolicy: Owner
  data:
    # SANDBOX credentials
    - secretKey: ppcp-sandbox-clientid
      remoteRef:
        key: ppcp-sandbox-clientid
    - secretKey: ppcp-sandbox-secret
      remoteRef:
        key: ppcp-sandbox-secret
    - secretKey: ppcp-sandbox-webhookid
      remoteRef:
        key: ppcp-sandbox-webhookid
    - secretKey: ppcp-sandbox-attributionid
      remoteRef:
        key: ppcp-sandbox-attributionid
    - secretKey: ppcp-sandbox-partnermerchantid
      remoteRef:
        key: ppcp-sandbox-partnermerchantid

    # PRODUCTION credentials
    - secretKey: ppcp-production-clientid
      remoteRef:
        key: ppcp-production-clientid
    - secretKey: ppcp-production-secret
      remoteRef:
        key: ppcp-production-secret
    - secretKey: ppcp-production-webhookid
      remoteRef:
        key: ppcp-production-webhookid
    - secretKey: ppcp-production-attributionid
      remoteRef:
        key: ppcp-production-attributionid
    - secretKey: ppcp-production-partnermerchantid
      remoteRef:
        key: ppcp-production-partnermerchantid

Important:

• ${secret_store_eso_sest_name} references the preconfigured Secret Store for your environment

• The resulting Kubernetes Secret (ppcp-secret) is managed automatically and kept in sync with Azure Key Vault.

Injecting Secrets via Helm

Instead of defining PayPal credentials directly in the environment section of the Helm deployment, use secretMounts (see GitHub: intershop/hem-charts | Attributes in Section secretMounts).

Example (e.g., icm.yaml):

icm-as:
...
  secretMounts:
    - secretName: ppcp-secret
      key: ppcp-sandbox-clientid
      targetEnv: INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_SANDBOX_CLIENTID
    - secretName: ppcp-secret
      key: ppcp-sandbox-secret
      targetEnv: INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_SANDBOX_SECRET
    - secretName: ppcp-secret
      key: ppcp-sandbox-webhookid
      targetEnv: INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_SANDBOX_WEBHOOKID
    - secretName: ppcp-secret
      key: ppcp-sandbox-attributionid
      targetEnv: INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_SANDBOX_ATTRIBUTIONID
    - secretName: ppcp-secret
      key: ppcp-sandbox-partnermerchantid
      targetEnv: INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_SANDBOX_PARTNERMERCHANTID

    - secretName: ppcp-secret
      key: ppcp-production-clientid
      targetEnv: INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_PRODUCTION_CLIENTID
    - secretName: ppcp-secret
      key: ppcp-production-secret
      targetEnv: INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_PRODUCTION_SECRET
    - secretName: ppcp-secret
      key: ppcp-production-webhookid
      targetEnv: INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_PRODUCTION_WEBHOOKID
    - secretName: ppcp-secret
      key: ppcp-production-attributionid
      targetEnv: INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_PRODUCTION_ATTRIBUTIONID
    - secretName: ppcp-secret
      key: ppcp-production-partnermerchantid
      targetEnv: INTERSHOP_PAYMENT_PAYPAL_CHECKOUT_PRODUCTION_PARTNERMERCHANTID

Using Docker Compose to Start the Server with the Extension Image

1. Ensure that the database and required infrastructure is running.

2. Mount the customization layer or reference the combined image.

3. Extend CARTRIDGE_LIST to include ft_ppcp.

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

Example (simplified excerpt):

services:
    customize-paypal-complete-payments:
        image: intershophub/icm-as-customization-paypal-complete-payments:<TAG>
        volumes:
            - customizations:/customizations
...
    appserver:
        depends_on:
        - customize-paypal-complete-payments
...
        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>"            

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.

Customizing 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, performing 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) and replace <TAG> by the version you consume:

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

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 for the PayPal Complete Payments Connector.

In general, Intershop recommends configuring the PayPal services on channel level. The configuration model is divided into a shared PayPal Common Configuration service and payment method-specific service configurations.

The PayPal Common Configuration service is the central configuration entry point for shared PayPal settings. It is used for merchant onboarding and for runtime settings that apply across the PayPal payment services. Payment method-specific services build on this shared configuration model rather than duplicating common PayPal account setup.

Service Definitions

You can enable the payment service either via the UI in the Organization Management (see Cookbook - Payment | Recipe: Enable a Payment Service), or by using DBPrepare. If you choose the DBPrepare option, use the following service definitions.

PayPal Common Configuration

PayPal

PayPal Express Checkout

PayPal Credit Card

PayPal Apple Pay

PayPal Google Pay

Applying UI-Based Configuration

Configuration in ICM is organized in two layers: a shared PayPal Common Configuration service for merchant onboarding and common runtime settings, and service-specific configurations for the individual PayPal payment services. This separation keeps shared account-level settings centralized while allowing each service to be configured independently.

Intershop recommends completing the onboarding process in the PayPal Common Configuration service before configuring the individual payment services.

Onboarding

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

Intershop recommends completing the PayPal onboarding in the Common Configuration service before configuring the individual payment method-specific services.

Follow these steps:

1. Create the managed service for the PayPal common configuration 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.
   Please note that the environment cannot be changed as soon as a PayPal Account is connected to this service, because the account belongs to this environment. To change the value, you need to disconnect and reconnect after changing the environment.

   

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

   

4. Finally, you are redirected and can configure the details of the service. Details about the connected account are shown at the bottom of the page for reference. In the section Pay Later and Messaging, 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.

The table below lists possible settings you can configure for the payment service. Please note that not all of them are available for each service.

Localization

You can find the existing localization files for storefront-relevant artifacts 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

Rounding Errors

Rounding errors can occur when transmitting basket data to a payment service provider. If a PSP’s API expects basket totals (for example, shipping, taxes, and discounts) as values with two decimal places, the sum of these rounded amounts may differ from the original total amount (calculated with higher precision, such as 5 decimals) used for authorization. Even a difference of a single cent can be enough for the PSP to reject the payment.

These rounding issues are typically caused by price calculations involving percentage values, for example:

• Converting net prices into gross prices (for instance, when prices are stored as net values in the back office but displayed as gross in the storefront)

• Percentage‑based discounts

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

Redirecting on Significant Cart Changes

If a basket changes (pricing, items, shipping) after the initial PayPal approval, a re-initiation flow ensures that PayPal has accurate amounts.

Onboarding

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.

Webhooks

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

Data Handling

This section describes the data transmitted by Intershop to external payment systems as part of the PayPal Complete Payments Connector flow. It focuses on data sent by the connector itself and does not describe internal processing or downstream transfers within third-party payment platforms.

The tables in the sub sections list the data elements transmitted by the connector to PayPal and the wallet provider during payment processing. Depending on the payment method and configuration, not all data elements are sent in every scenario.

Data transmitted from Intershop to PayPal

Legend: - Transmitted / - Not Transmitted / - Optional (sent when enabled in configuration)

Data used in wallet-based payment initiation on the storefront side

Legend: - Transmitted / - Not Transmitted

Limitations

Application Types

Only REST (PWA storefront) is officially supported by the releases of the major version 3.

Digital Goods Support

The connector supports payments for baskets with digital goods. The PWA does not fully support this at the moment.

Time Limit for Order Creation

Apple Pay and Google Pay require that the process of starting a payment, completing an order, and reporting the completion status back to the wallet provider be completed within 30 seconds. This restricts orders based on the number of line items and promotions.

Webhook Notification Support Disabled

Processing of PayPal webhook events has been disabled in this version due to data privacy concerns.

ICM Customization

The PayPal Complete Payments Service connector overwrites the following templates of the ICM back office:

• ServiceConfigurationParameterGroup.isml

• ServicesEditConfiguration_inc.isml

If these files have to be customized in another ICM customization or the integration project, the special handling has to be merged in the project.

This approach ensures broad compatibility across multiple ICM versions.

ICM Version Limitations

ICM versions 13.0.0–13.5.2 and 14.0.1–14.0.2 do not allow updating data stored in the payment instrument if it was initially empty. As a result, the used credit card is not displayed in the storefront in that case. This does not affect functionality. To resolve this issue, update to the latest version of the major release used in the project.

Migration Guides

Read PayPal Capabilities for Apple Pay and Google Pay

Apple Pay and Google Pay require reading the corresponding capabilities from PayPal. This is done every time the Integration tab of the PayPal Common Configuration is opened. Open the page once to let ICM re-read the latest capabilities from PayPal. This is only necessary when one of these payment methods is intended to be used.

PayPal Complete Payments Connector 2.1.x to 3.0.2

The onboarding required per service was extracted from the single payment services and moved to a dedicated service for common configuration valid for all services. Since there could be multiple configurations, it is not possible to pick the correct payment service as source for the migration. As a result, the onboarding has to be repeated once for the PayPal Common Configuration service.

The handling of the Pay Later and Messaging preferences was moved to the same PayPal Common Configuration. Apply your preferred settings there. The channel preference for PayPal Complete Payments was removed.

PayPal (Standard) Service Connector 8 to PayPal Complete Payments Connector 2

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, do not activate both connectors for customers, as this can cause confusion.

Recommended steps for switching integrations:

1. Deploy to non-production.

2. Enable ft_ppcp alongside ft_paypal.

3. Onboard the same merchant that was 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 remain available.

Changelog

Version 3.1.1

• Fix: Resilient handling and logging of missing PayPal credentials configuration

• Fix: Show section description for common configuration service

• i18n: Updated localizations

Version 3.1.0

• New feature: Support for payments with Apple Pay and Google Pay

• New feature: Allow onboarding when the PayPal Common Configuration is still inactive

• Combined the detailed order transmission options “All details as subtotal” and “Details separated” into a single option, “Detailed order data”

• Upgrade to PayPal Server SDK 2.2.0

Version 3.0.2

• Added support for credit card payments

• Combined onboarding into a common configuration service

• Moved channel preferences for Pay Later and Messaging to the common service

Version 2.1.2

• Fixed a potential exception when de-serializing the received product names in the GET Seller Status call to PayPal

Version 2.1.1

• Fixed an issue preventing merchant onboarding in Production environment

• Fixed a potential NullPointerException when logging failed requests to PayPal

Version 2.1.0

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