connect-payment-integration-template

This repository provides a commercetools connect integration for Stripe payment, enabling a drop-in experience through the Stripe Payment Element and supporting webhook handling, payment intents, and checkout configuration.

Features

• Uses commercetools SDK for the commercetools-specific communication.
• It uses connect payment SDK to manage request context, sessions, and JWT authentication.
• Use commercetools payment api to manage payment transactions.
• Includes local development utilities in npm commands to build, start, test, lint & prettify code.
• Supports the Payment Element component and layout configuration.
• Backend (processor) use the Stripe API for creating and managing payment intents, handling webhooks, and processing payments.
• Customer session management for Stripe, including customer creation and retrieval.Considerations
• Transfer of shipping information from commercetools to Stripe payment intent.
• Support for Buy Now Pay Later (BNPL) payment method.Considerations
• Enhanced refund processing with support for multiple refunded events, ensuring accurate refund data synchronization between Stripe and commercetools.
• Payment cancellation logic with improved amount handling and streamlined processing flow. More information in Payment Cancellation
• Multicapture Support: Comprehensive support for multiple partial captures on the same payment intent, enabling complex fulfillment scenarios and staged payment processing. More information in Multicapture Support
• Stripe Tax Calculation Integration: Support for automatic tax calculations on payment intents. When a cart has a tax calculation reference in the custom field connectorStripeTax_calculationReferences, it will be automatically applied to the payment intent. More information in Stripe Tax Calculation
• Stripe Express Checkout: Support for the Stripe Express Checkout Element, aligned with commercetools Checkout Express integration (callbacks, checkout session via onPayButtonClick on each wallet open, cart updates). Includes processor endpoints GET /express-payment-data and POST /express-config, shipping-related enabler callbacks, and PaymentIntent creation without shipping when the frontend sends x-express-checkout. More detail in Express Checkout and the processor APIs.

Prerequisite

1. commercetools composable commerce API client

Create an API client responsible for payment management in a composable commerce project. The API client details are input as environment variables/ configuration for connect, such as CTP_PROJECT_KEY, CTP_CLIENT_ID, and CTP_CLIENT_SECRET. Please read Deployment Configuration for details.
In addition, please make sure the API client has enough scope to manage Payment. For details, please refer to Running Application

2. Various URLs from commercetools composable commerce

Configure various URLs from the commercetools platform, so that the connect application can handle the session and authentication process for endpoints.
Their values are input for environment variables/configurations for connecting, with variable names CTP_API_URL, CTP_AUTH_URL, and CTP_SESSION_URL.

3. Stripe account and keys

Configure Stripe secret and public keys so the Connect application can handle endpoint session and authentication processes. Their values are taken as input as environment variables/ configuration for Connect, with variable names STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY, and STRIPE_WEBHOOK_SIGNING_SECRET.

Getting started

The connect-payment-integration-stripe contains two modules:

• Enabler: This is a wrapper implementation where Stripe frontend Payment Element and Express Checkout Element components are embedded. It gives checkout the control over when and how to load the connector frontend based on business configuration. Use createExpressBuilder(type) (e.g. type: 'dropin') for Express flows that follow commercetools Checkout Express expectations. More information in Express Checkout.
• Processor: This functions as a backend service and middleware for integration with the Stripe platform. It interacts with Stripe for transactions and updates the payment entity within Composable Commerce. Finding the Stripe customer that own the commercetools cart, or creating the customer and adding the information to the custome field of the cart. Additionally, it supports a listener for triggers related to Stripe webhook events to update the payment entity with connect-payment-sdk based on webhook events.

Regarding the development of a processor or enabler module, please refer to the following documentation:

• Development of Processor
• Development of Enabler

Components

1. commercetools Checkout
   Represents the Checkout platform infrastructure provided by commercetools.
2. Payment Connector
   • A Payment connector integration within the infrastructure of commercetools that facilitates communication between commercetools and Stripe.
3. Processor
   • Manages payment transactions and interacts with Stripe to:
     • Create payment intents.
     • Handle manual API payment transactions.
     • Listening to webhooks events triggered by Stripe and processing all related payment operations.
     • Create Stripe customer session
     • Refund processing with support for multiple refunded events and accurate data synchronization
4. Enabler
   • Assists in creating the Stripe Payment Element and Stripe Express Checkout Element components used as payment methods in the commercetools Checkout.
   • Connects to any sample site that wants to integrate the connector, providing the available payment components (dropins, components, and express) for seamless integration.
5. Stripe
   • The external payment service provider that handles various payment operations sends webhooks for events such as authorization, capture, refund, and cancel.

Webhooks

The following webhooks are currently supported, and the payment transactions in commercetools are:

• payment_intent.canceled: Modified the payment transaction Authorization to Failure and create a payment transaction CancelAuthorization: Success. Now includes proper amount handling for canceled payments using the enhanced populateAmountCanceled method.
• payment_intent.succeeded: Creates a payment transaction Charge: Success.
• payment_intent.payment_failed: Modify the payment transaction Authorization to Failure.
• payment_intent.requires_action: Logs the information in the connector app inside the Processor logs.
• charge.refunded: Creates a payment transaction Refund to Success and a Chargeback to Success. When STRIPE_ENABLE_MULTI_OPERATIONS is enabled, the system uses enhanced refund tracking to properly handle multiple refund events by retrieving the latest refund information from Stripe. When disabled, basic refund tracking is used. More information in Enhanced support for multiple refunded events
• charge.succeeded: Create the payment transaction to ‘Authorization:Success’ if charge is not capture.
• charge.updated: Creates a partial payment transaction Charge: Success with the partial amount. Note: This webhook is only processed when STRIPE_ENABLE_MULTI_OPERATIONS is enabled. This supports multicapture scenarios where multiple partial captures are performed on the same payment intent. More information in Multicapture Support

Prerequisite

1. Stripe account credentials and configurations

Before installing the connector, you must create a Stripe account and obtain the necessary credentials. The Stripe account is required to process payments and manage transactions. Sign up for a Stripe account at Stripe. Once you have an account, you must set up the following configurations in your environment variables or configuration files. Before installing the connector, a webhook endpoint in Stripe must be created (using a dummy URL). Retrieve the ID and Signing Secret from the Stripe Console. The Webhook Endpoint is update during the post-deploy script after the deployed connector. It’s important to set the correct values in the variables so the events are sent to the connector and can be accepted. The following Stripe account credentials and configurations are required:

1. STRIPE_SECRET_KEY: Provided by Stripe. Secret and stored securely in your web or mobile app’s server-side code (such as in an environment variable or credential management system) to call Stripe APIs.
2. STRIPE_CAPTURE_METHOD: Configuration that enables the capture method selected by the user. The capture method controls when Stripe will capture the fundsthe customer’s account. Possible enum values:
      - automatic: Stripe automatically captures funds when the customer authorizes the Payment.
      - automatic_async: (Default) Stripe asynchronously captures funds when the customer authorizes the Payment. Recommended over capture_method=automatic due to improved latency. Read the integration guide for more information.
      - manual: Places a hold on the funds when the customer authorizes the Payment but doesn’t capture the funds until later. (Not all payment methods support this.)
3. STRIPE_APPEARANCE_PAYMENT_ELEMENT: This configuration enables the theming for the payment element component. The value needs to be a valid stringified JSON. More information about the properties can be found here.

//stringified, eg.
{"theme":"night", "labels":"floating"}

4. STRIPE_WEBHOOK_ID: Unique identifier of a Webhook Endpoint in Stripe.
5. STRIPE_WEBHOOK_SIGNING_SECRET: Signing Secret of a Webhook Endpoint in Stripe.
6. STRIPE_LAYOUT: This configuration enables the Layout for the payment component. The value needs to be a valid stringified JSON. More information about the properties can be found here.

//stringified, eg.
{"type":"accordion","defaultCollapsed":false,"radios":true, "spacedAccordionItems":false}

7. STRIPE_SAVED_PAYMENT_METHODS_CONFIG: The configuration for the saved payment methods. The value needs to be a valid stringified JSON. More information about the properties can be found here. This feature is disabled by default. To enable it, you need to add the expected customer session object.

//stringified, eg.
{"payment_method_save_usage":"off_session","payment_method_redisplay_limit":10}

8. STRIPE_PUBLISHABLE_KEY: Provided by Stripe. The key is to create the Payment Element component on the front end.
9. STRIPE_APPLE_PAY_WELL_KNOWN: This is the domain association file from Stripe. Use to verify the domain for Apple Pay. More information can be found here.
10. MERCHANT_RETURN_URL: This is the return URL used on the confirmPayment return_url parameter. The Buy Now Pay Later payment methods will send the Stripe payment_intent in the URL; the Merchant will need to retrieve the payment intent and look for the metadata ct_payment_id is add in the commercetools Checkout SDK paymentReference.
11. STRIPE_CAPTURE_METHOD: This is the capture method used for the Payment. It can be either automatic or manual. The default value is automatic.
12. STRIPE_WEBHOOK_ID: This is the unique identifier for the Stripe Webhook Endpoint.
13. STRIPE_COLLECT_BILLING_ADDRESS: This is the configuration for the Stripe collect billing address in the payment element. The default value is auto. More information can be found here.
14. STRIPE_ENABLE_MULTI_OPERATIONS: This is an opt-in feature flag to enable advanced multicapture and multirefund support. When enabled (true), the connector processes multiple partial captures and refunds on a single payment. The default value is false. Important: This feature requires multicapture to be enabled in your Stripe account. More information in Multicapture Support and Enhanced Refund Processing.
15. STRIPE_PAYMENT_INTENT_SETUP_FUTURE_USAGE: Override the setup_future_usage value for PaymentIntent creation. This decouples the PaymentIntent’s setup_future_usage from the Customer Session’s payment_method_save_usage configuration. Possible values:
    • off_session: Payment method will be used for future off-session payments
    • on_session: Payment method will be used for future on-session payments
    • Empty string, none, null, or undefined: Do NOT include setup_future_usage in PaymentIntent
16. CT_CUSTOM_TYPE_LAUNCHPAD_PURCHASE_ORDER_KEY: Custom type key for launchpad purchase order number. Default: payment-launchpad-purchase-order
17. CT_CUSTOM_TYPE_STRIPE_CUSTOMER_KEY: Custom type key for storing Stripe customer ID on commercetools customers. Default: payment-connector-stripe-customer-id
18. CT_CUSTOM_TYPE_SUBSCRIPTION_LINE_ITEM_KEY: Custom type key for subscription line items. Default: payment-connector-subscription-line-item-type
19. CT_PRODUCT_TYPE_SUBSCRIPTION_KEY: Product type key for subscription information. Default: payment-connector-subscription-information
20. STRIPE_API_VERSION: Stripe API version to use for API requests. Default: 2025-12-15.clover
21. STRIPE_EXPRESS_ELEMENT_OPTIONS: Optional JSON configuration for the Express Checkout Element options. Supported fields: buttonHeight, buttonTheme, buttonType, emailRequired, layout, paymentMethodOrder, phoneNumberRequired. The value needs to be a valid stringified JSON. Example: {"buttonHeight":48,"emailRequired":true,"paymentMethodOrder":["apple_pay","google_pay"]}. More information about the properties can be found in the Stripe Express Checkout Element docs.

2. commercetools

We must create the connector on the commercetools connect marketplace, enable the checkout feature in the merchant center, and select the payment connector as the drop-in payment method on the checkout configuration page. Users create an API client responsible for payment management in a composable commerce project. The API client’s details are input as environment variables/ configuration for connecting, such as CTP_PROJECT_KEY, CTP_CLIENT_ID, and CTP_CLIENT_SECRET.

1. **API client **: Various URLs from the commercetools platform must be configured so that the connect application can handle the session and authentication process for endpoints. Their values are taken as input as environment variables/ configuration for connect, with variable names CTP_API_URL, CTP_AUTH_URL, and CTP_SESSION_URL.
2. payment connector: Install the payment connector from the commercetools connector marketplace.
3. commercetools Checkout: Enable the checkout connector in the merchant center to install the current connector as a drop-in payment method in the checkout dashboard configuration page.

Development Guide

Changelog

For a detailed list of changes and enhancements, see CHANGELOG.md.

Deployment Configuration

It needs to be published to deploy your customized connector application on commercetools Connect. For details, please refer to documentation about commercetools Connect
In addition, the tax integration connector template has a folder structure, as listed below, to support Connect.

├── enabler
│   ├── src
│   ├── test
│   └── package.json
├── processor
│   ├── src
│   ├── test
│   └── package.json
└── connect.yaml

The connect deployment configuration specifie in connect.yaml, the information needed to publish the application. Following is the deployment configuration used by the Enabler and Processor modules

deployAs:
  - name: enabler
    applicationType: assets
  - name: processor
    applicationType: service
    endpoint: /
    scripts:
      postDeploy: npm install && npm run connector:post-deploy
      preUndeploy: npm install && npm run connector:pre-undeploy
    configuration:
      standardConfiguration:
        - key: CTP_PROJECT_KEY
          description: commercetools project key
          required: true
        - key: CTP_AUTH_URL
          description: commercetools Auth URL (example - https://auth.europe-west1.gcp.commercetools.com).
          required: true
          default: https://auth.europe-west1.gcp.commercetools.com
        - key: CTP_API_URL
          description: commercetools API URL (example - https://api.europe-west1.gcp.commercetools.com).
          required: true
          default: https://api.europe-west1.gcp.commercetools.com
        - key: CTP_SESSION_URL
          description: Session API URL (example - https://session.europe-west1.gcp.commercetools.com).
          required: true
          default: https://session.europe-west1.gcp.commercetools.com
        - key: CTP_CHECKOUT_URL
          description: Checkout API URL (example - https://checkout.europe-west1.gcp.commercetools.com).
          required: true
          default: https://checkout.europe-west1.gcp.commercetools.com
        - key: CTP_JWKS_URL
          description: JWKs url (example - https://mc-api.europe-west1.gcp.commercetools.com/.well-known/jwks.json)
          required: true
          default: https://mc-api.europe-west1.gcp.commercetools.com/.well-known/jwks.json
        - key: CTP_JWT_ISSUER
          description: JWT Issuer for jwt validation (example - https://mc-api.europe-west1.gcp.commercetools.com)
          required: true
          default: https://mc-api.europe-west1.gcp.commercetools.com
        - key: STRIPE_CAPTURE_METHOD
          description: Stripe capture method (example - manual|automatic).
          default: automatic
        - key: STRIPE_WEBHOOK_ID
          description: Stripe unique identifier for the Webhook Endpoints (example - we_*****).
          required: true
        - key: STRIPE_APPEARANCE_PAYMENT_ELEMENT
          description: Stripe Appearance for Payment Element (example - {"theme":"night","labels":"floating"} ).
        - key: STRIPE_LAYOUT
          description: Stripe Layout for Payment Element (example - {"type":"accordion","defaultCollapsed":false,"radios":true,"spacedAccordionItems":false} ).
          default: '{"type":"tabs","defaultCollapsed":false}'
        - key: STRIPE_PUBLISHABLE_KEY
          description: Stripe Publishable Key
          required: true
        - key: STRIPE_APPLE_PAY_WELL_KNOWN
          description: Domain association file from Stripe. (example - https://stripe.com/files/apple-pay/apple-developer-merchantid-domain-association)
        - key: STRIPE_SAVED_PAYMENT_METHODS_CONFIG
          description: Stripe configuration for saved payment methods (example - {"payment_method_save":"enabled","payment_method_save_usage":"off_session","payment_method_redisplay":"enabled","payment_method_redisplay_limit":10}).
          default: '{"payment_method_save":"disabled"}'
        - key: MERCHANT_RETURN_URL
          description: Merchant return URL
          required: true
        - key: PAYMENT_INTERFACE
          description: The payment interface value used in the commercetools payment/payment methods. Default value is "checkout-stripe".
          required: false
        - key: STRIPE_COLLECT_BILLING_ADDRESS
          description: Stripe collect billing address information (example - 'auto' | 'never' | 'if_required').
          default: 'auto'
          required: true
        - key: STRIPE_ENABLE_MULTI_OPERATIONS
          description: Enable multicapture and multirefund support. Requires multicapture to be enabled in your Stripe account (example - true | false).
          default: 'false'
      securedConfiguration:
        - key: CTP_CLIENT_SECRET
          description: commercetools client secret.
          required: true
        - key: CTP_CLIENT_ID
          description: commercetools client ID with manage_payments, manage_orders, view_sessions, view_api_clients, manage_checkout_payment_intents, introspect_oauth_tokens, manage_types and view_types scopes
          required: true
        - key: STRIPE_SECRET_KEY
          description: Stripe secret key (example - sk_*****).
          required: true
        - key: STRIPE_WEBHOOK_SIGNING_SECRET
          description: Stripe Webhook signing secret  (example - whsec_*****).
          required: true

Here, you can see the details about various variables in the configuration

• CTP_PROJECT_KEY: The key to the commercetools composable commerce project.

• CTP_SCOPE: The scope constrains the endpoints to which the commercetools client has access and the read/write access right to an endpoint.

• CTP_AUTH_URL: The URL for authentication in the commercetools platform. Generate the OAuth 2.0 token required in every API call to commercetools composable commerce. The default value is https://auth.europe-west1.gcp.commercetools.com. For details, please refer to the documentation here.

• CTP_API_URL: The URL for commercetools composable commerce API. The default value is https://api.europe-west1.gcp.commercetools.com.

• CTP_SESSION_URL: The URL for session creation in the commercetools platform. Connectors rely on the session created to share information between the enabler and processor. The default value is https://session.europe-west1.gcp.commercetools.com.

• CTP_JWKS_URL: The JSON Web Key Set URL. Default value is https://mc-api.europe-west1.gcp.commercetools.com/.well-known/jwks.json

• CTP_JWT_ISSUER: The issuer inside JSON Web Token, required in the JWT validation process. The default value is https://mc-api.europe-west1.gcp.commercetools.com

• STRIPE_CAPTURE_METHOD: Stripe capture method (manual or automatic), default value: automatic.

• STRIPE_APPEARANCE_PAYMENT_ELEMENT: Stripe Elements supports visual customization, which allows you to match the design of your site with the appearance option. This value has the specific appearance of the Payment Element component. The value needs to be a valid stringified JSON. More information about the properties can be found here.

• STRIPE_LAYOUT: Stripe allows you to customize the Payment Element’s Layout to fit your checkout flow (accordions or tabs). Default value is {"type":"tabs","defaultCollapsed":false}

• CTP_CLIENT_SECRET: The client secret of commercetools composable commerce user account. It is used in commercetools for clients to communicate with commercetools composable commerce via SDK.

• CTP_CLIENT_ID: The client ID of your commercetools composable commerce user account. It is used in commercetools for clients to communicate with commercetools composable commerce via SDK. Expected scopes are: manage_payments manage_orders view_sessions view_api_clients manage_checkout_payment_intents introspect_oauth_tokens manage_types view_types.

• STRIPE_SECRET_KEY: Stripe authenticates your API requests using your account’s API keys

• STRIPE_PUBLISHABLE_KEY: Stripe authenticates your frontend requests using your account’s Publishable keys

• STRIPE_WEBHOOK_ID: Stripe unique identifier for the Webhook Endpoints

• STRIPE_WEBHOOK_SIGNING_SECRET: Stripe Secret key to verify webhook signatures using the official libraries. This key created in the Stripe dashboard Webhook.

• STRIPE_APPLE_PAY_WELL_KNOWN: Domain association file from Stripe. We can find more information in this link.

• MERCHANT_RETURN_URL: Merchant return URL used on the confirmPayment return_url parameter. The Buy Now Pay Later payment methods will send the Stripe payment_intent in the URL; the Merchant will need to retrieve the payment intent and look for the metadata ct_payment_id to be added in the commercetools Checkout SDK paymentReference.

• STRIPE_SAVED_PAYMENT_METHODS_CONFIG: Stripe allows you to configure the saved payment methods in the Payment Element, refer to docs. This feature is disabled by default. To enable it, you need to add the expected customer session object. Default value is {"payment_method_save":"disabled"}

  Important: When using commercetools Recurring Orders, this configuration will be automatically overridden to enable payment method storage. Recurring payment workflows require the payment method to be saved for future charges, so the connector will set payment_method_save_usage to "off_session" regardless of your configuration. This ensures compatibility with recurring order processing and future subscription charges.

• STRIPE_COLLECT_BILLING_ADDRESS: Stripe allows you to collect the billing address in the Payment Element. Possible values: auto, never, if_required. The default value is auto. More information can be found here.

• STRIPE_ENABLE_MULTI_OPERATIONS: Opt-in feature flag to enable advanced multicapture and multirefund support. When set to true, enables processing of multiple partial captures and refunds on a single payment intent. Default value is false. Important: This feature requires multicapture to be enabled in your Stripe account settings. See Multicapture Support and Enhanced Refund Processing for implementation details.

• STRIPE_EXPRESS_ELEMENT_OPTIONS: Optional JSON configuration for the Express Checkout Element options. Supported fields: buttonHeight, buttonTheme, buttonType, emailRequired, layout, paymentMethodOrder, phoneNumberRequired. The value needs to be a valid stringified JSON. Example: {"buttonHeight":48,"emailRequired":true,"paymentMethodOrder":["apple_pay","google_pay"]}. More information in the Stripe Express Checkout Element docs.

• STRIPE_PAYMENT_INTENT_SETUP_FUTURE_USAGE: Override the setup_future_usage value for PaymentIntent creation independently from Customer Session configuration. Values: off_session, on_session, or empty/none/null/undefined to exclude it from PaymentIntent. Note: Recurring carts always use off_session regardless of this override to ensure compatibility with recurring order processing.

• CT_CUSTOM_TYPE_LAUNCHPAD_PURCHASE_ORDER_KEY: Custom type key for launchpad purchase order number. Default: payment-launchpad-purchase-order

• CT_CUSTOM_TYPE_STRIPE_CUSTOMER_KEY: Custom type key for storing Stripe customer ID. Default: payment-connector-stripe-customer-id

• CT_CUSTOM_TYPE_SUBSCRIPTION_LINE_ITEM_KEY: Custom type key for subscription line items. Default: payment-connector-subscription-line-item-type

• CT_PRODUCT_TYPE_SUBSCRIPTION_KEY: Product type key for subscription information. Default: payment-connector-subscription-information

• STRIPE_API_VERSION: Stripe API version to use for API requests. Default value is 2025-12-15.clover. This version is used when creating ephemeral keys for customer sessions.

Development

Certain configurations are necessary to get started developing this connector, most of which involve updating environment variables in both services (enabler, processor).
Creating a Webhook Endpoint in Stripe (using a dummy URL) is necessary. Once created, retrieve the ID and Signing Secret from the Stripe Console. The Webhook Endpoint configuration is update during the post-deploy script after the connector is deploy. It’s important to set the correct values in the variables so the events are sent to the connector and can be accepted.

Configuration steps

1. Environment Variable Setup

Navigate to each service directory and duplicate the .env.template file, renaming the copy to .env. Populate the newly created .env file with the appropriate values.

cp .env.template .env

2. Spin Up Components via Docker Compose

With the help of docker compose, you can spin up all necessary components required for developing the connector by running the following command from the root directory;

docker compose up

This command would start three services that are required for development.

1. JWT Server
2. Enabler
3. Processor