Introduction

Welcome to version 3 of the Intershop PayPal Complete Payments Service Connector.
This connector is a complete, modernized rewrite of the previous “PayPal Service Connector” and integrates with PayPal using the PayPal REST APIs for payment operations and merchant onboarding.

Unlike the previous connector generation, this solution is explicitly designed for use within the PayPal Partner Program. Intershop provides this integration in the role of a PayPal technology partner, enabling merchants to onboard and use PayPal via a partner‑managed setup flow. Correspondingly, the connector replaces the former PayPal Service Connector 8, which relied on the legacy PayPal Classic API.

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 outlines the version’s scope, dependencies, configuration, 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 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 SecretStore 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):

   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.

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

Applying UI-Based Configuration

The UI-based configuration is divided into two sections: one common service configuration used by all payment services for PayPal Complete Payments, and the payment method-specific service configuration.

Onboarding

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

It is recommended to complete the onboarding process before configuring the individual 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

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 3.0.2 release.

Digital Goods Support

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

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.0–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

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. Please 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, 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. 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.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