Introduction

Welcome to the Intershop Stripe Checkout Connector, a service connector designed to seamlessly integrate a payment method into your Intershop Commerce Management installation by leveraging Stripe's robust Checkout API. Stripe is a leading online payment processing platform trusted by businesses around the world for secure and efficient transaction handling.
This release note provides key insights into product version details, dependencies, and comprehensive setup and configuration instructions to optimize your integration process.

References

• Stripe

• Stripe Checkout API

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

Since there is no dependency between the PWA and the Stripe connector, the required PWA version depends only on the ICM version used.

The Stripe Checkout Connector 1 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.

The image is available in the respective Docker repository: intershophub/icm-as-customization-stripe-checkout

Compatibility of Application Types

The Stripe Checkout Connector can be used for the following application types:

Feature Overview

Payment Methods

The Stripe Checkout Connector adds a single generic payment option per service configuration to your Intershop Commerce Management System, typically combining multiple specific payment methods.
The buyer selects the actual payment method after being redirected to the Stripe payment page. The payment methods available there can be configured in the Stripe dashboard. It is also possible to set up Payment Method Configurations via the dashboard, which can then be referenced by their ID in the payment service configuration.

Payment Management Options

Order Detail Transmission Options

The Stripe Checkout Connector supports the option to send detailed order information to Stripe (“Detailed” mode). However, there are several limitations to this mode, both on the Stripe side and on the ICM side. These are explained in the Limitations section.
Alternatively, the order information can be consolidated and sent as a grand total only (“Consolidated” mode). In this case, the above limitations do not apply.

Setup

The customization image for the Stripe Checkout Connector is available from Intershop's public repository. To add the customization image for the Stripe Checkout Connector to your project, you must add it to the dependencies of your customization. To achieve this, several steps are required:

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

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

2. Add dependencies to the Stripe Checkout 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 ...
   
       // Stripe Checkout Connector
       cartridgeRuntime ("com.intershop.services.payment_stripe_checkout:ft_stripe_checkout")
   }

   To include the Stripe Checkout 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"))
           // alternative scenario using a feature cartridge where Stripe Checkout isn't included as a runtime dependency:
           // cartridgeList.set(setOf("ft_stripe_checkout", "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 compose file used to tell ICM which cartridges to load. This can be done using the CARTRIDGE_LIST environment variable of the app server.

      version: "3.8"
      services:
        customize-stripe:
          image: icm-as-customization-stripe-checkout:<stripe-connector-version-tag>
          volumes:
            - customizations:/customizations
        # ... other services ...
        appserver:
          # ... other appserver settings ...
          container_name: appserver
      
          environment:
            # ... more environment variables ...
            # example cartridge list (assuming the Stripe Checkout Connector (ft_stripe_checkout) is already defined as dependency). Please adapt to your needs.
            CARTRIDGE_LIST: "ft_myproject"    
      
      # ... more configuration ...

   3. Production environment using Helm charts:
      If you are using Helm to manage the ICM instances, you will need to adjust the cartridge list. Please follow Concept - Customization ICM 11 - Deployment to add the Stripe Checkout Connector cartridges to this list.

For details on managing the artifacts, see:

• Concept - Customization - Development - ICM 11+

• Concept - Customization ICM 11 - Deployment

Configuration

File-Based Configuration

A part of the payment method configuration is not meant to be changed in the Commerce Management application and is available through server properties. These properties are read by the configuration framework and as such can be overridden for an application type. They can be overridden within your custom cartridges <cartridge_name>/src/main/resources/cartridges/<cartridge_name>.properties or by specifying properties files under <cartridge_name>/src/main/resources/resources/<cartridge_name>/config.

For more information on the configuration framework, check Concept - Configuration and Cookbook - Configuration.

Supported Currencies

The Stripe Checkout Connector requires the following settings for the currencies you want to support:

Supported Countries

A list of supported countries can be defined for each payment method. A comma-separated list of ISO 3166 ALPHA 2 country codes is valid:

Webhook Notification Sources

The Stripe Checkout Connector receives webhook notifications from Stripe. To ensure that the messages actually come from Stripe, the valid IP addresses must be on the whitelist. This does not replace filtering in the firewall.

In addition to the source IP address verification, the Signing Secret is used to verify the received event. See the next chapter for details on the configuration value.

Applying UI-Based Configuration

The Stripe Checkout Connector requires some post-deployment configuration in Intershop Organization Management and Intershop Commerce Management.

For details about on a payment service, see Cookbook - Payment | Recipe: Enable a Payment Service.
The table below lists Stripe Checkout-specific settings you can enter at the payment service.

General Settings

Payment Methods

Stripe Account Configuration

To use this Payment Connector, you need a Stripe account that is linked to the Intershop Stripe platform account as a Connected Account.

You have to contact Intershop Support for assistance with the onboarding process. Intershop will provide you an Access URL link to create and manage your private Stripe Backoffice as first step.

When you set up your Stripe account, you will also receive your Stripe Account ID, which must be set as Account ID in your Stripe service configuration.

In addition to the Account ID, a Stripe API key is required to authenticate communication between the Payment Connector and Stripe. This cannot be set explicitly in the service configuration, but will be provided by Intershop via your system environment.

Stripe Events and Webhook Endpoint

The Stripe Checkout Connector provides a webhook endpoint to receive events sent by Stripe and process the payment transactions accordingly. In order for the payment connector to function properly, it is necessary to register this webhook endpoint within the Stripe Dashboard.

See Stripe | Receive Stripe events in your webhook endpoint for detailed explanations about Stipe events.

Your starting point to configure webhooks in the Stripe Dashboard is Developers > Webhooks.

Webhook can be created in the Developer Section .

Create a Webhook Endpoint

To connect your Stripe account to your ICM and the Stripe Payment Connector, the webhook must be configured with the following settings:

Retrieving your Endpoint’s Secret

Once the webhook endpoint has been successfully created, you can find its signing secret in the details view of the webhook. This secret usually looks like “whsec_*******“. Copy this value and use it as the “Signing Secret” in your Stripe service configuration. The secret is used by the connector to validate all incoming (signed) events and ensure that they are actually coming from Stripe.

Localization

The Stripe Checkout Connector provides English, French 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_stripe_checkout/release/localizations

For details about localization, see:

• Concept - Localization

• Cookbook - Localization

Data Handling

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

Limitations

The transmission of detailed order information implies various limitations:

Max number of line items

The Stripe Checkout API allows to transmit up to 100 line items. It is recommended by Stripe to consolidate line items if there are more than a few dozen. Please use the option Consolidated for the Order Details configuration entry.

Not Combinable with Limited Tender Payments

The Stripe Checkout API does not support the transmission of other payment methods, so it is not possible to combine transmitting order details with the use of multiple payments. If a storefront user has a limited tender payment assigned to the basket, the Stripe Checkout payment method will be marked as 'restricted'. If this is a common use case in the shop, Intershop recommends to use the Consolidated option for the Order Details configuration entry.

Possible Rounding Issues and Deviations in the Order Total Amount

Rounding errors can occur when transmitting order details to Stripe. In case of transmitting detailed order information, Stripe will calculate the order total on their side. There is a possibility that the recalculation on the PSP side will produce a different result than the total authorization amount calculated by the ICM. It is also possible that certain surcharges may not be transmitted to Stripe in detailed mode if there is no equivalent for this surcharge type on the Stripe side.

Rounding issues are caused by price calculations that include percentage values. For example:

• Converting net prices to gross prices. This can happen when prices are treated as net in the back office and displayed as gross in the storefront.

• Percentage-based discounts

To prevent the Stripe checkout page from displaying a different payment amount to the buyer than the previous review page, the amount calculated by Stripe is compared to the amount calculated by the ICM. If a difference is detected, the payment process will be aborted and not redirected to Stripe.

When using the “Consolidated” mode, these potential differences will not occur.

Avoiding Rounding Errors

The connector provides the option to disable the transfer of order details.

Back Office Option	Possible Rounding Issues	Explanation	Result at Stripe
Consolidated	no	Stripe does not display any details other than the total amount to be paid with Stripe Checkout. The payment total is the order total minus the amount paid with limited tender payments.
Detailed	yes	The connector uses most of the Stripe Checkout API. Order details appear at Stripe at dedicated places.

Changelog

Version Stripe Checkout/1.0.0

• Initial implementation