Stripe + commercetools Checkout Connector

What This Is

A commercetools Connect payment connector that integrates Stripe into the commercetools Checkout product (pre-built checkout, part of their Payment Hub framework). It supports the Stripe Payment Element and Express Checkout Element via commercetools' drop-in framework.

What This Is NOT

• This is NOT a storefront or commerce solution — merchants build their own
• This does NOT manage order state — commercetools Checkout handles that automatically
• This does NOT enforce a reference architecture for order flows
• Source code is public; merchants can use it natively from the Connect marketplace or fork it as a "custom connect application"

Two-Module Architecture

Enabler (enabler/) — Frontend Assets

Vite-bundled library deployed as assets via Connect. Wraps Stripe.js elements for commercetools' drop-in framework.

Two initialization paths:

• Session flow (_Setup): fetches /config-element/payment + /operations/config + /customer/session using x-session-id header
• Express no-session flow (_SetupExpress): fetches POST /express-config (CORS-only, no session needed)

Supported builders:

• createDropinBuilder('embedded') → Stripe Payment Element
• createExpressBuilder('dropin') → Stripe Express Checkout Element
• createComponentBuilder(type) → individual components (currently empty)

Processor (processor/) — Backend Service

Fastify HTTP service deployed as service via Connect.

API Endpoints

Stripe Payment Routes

Operation Routes

Webhook Event → CT Transaction Mapping

Events route through StripeEventConverter.convert() which extracts ct_payment_id from metadata.

Key Patterns and Conventions

CT ↔ Stripe Linking

• metadata.ct_payment_id on PaymentIntent links to commercetools payment ID
• stripeConnector_stripeCustomerId custom field on CT customer stores Stripe customer ID
• connectorStripeTax_calculationReferences cart custom field feeds Stripe Tax

Feature Flag: STRIPE_ENABLE_MULTI_OPERATIONS

When true:

• charge.refunded → enhanced processStripeEventRefunded() (queries Stripe for latest refund)
• charge.updated → processStripeEventMultipleCaptured() (partial capture tracking)
• PaymentIntent created with request_multicapture: 'if_available'
• Partial captures use final_capture: false

When false (default):

• charge.refunded → basic converter flow
• charge.updated → skipped
• Partial capture attempts throw error

Payment Interface

Default: checkout-stripe (configurable via PAYMENT_INTERFACE)

Stripe API Version

Default: 2025-12-15.clover (configurable via STRIPE_API_VERSION)

Custom Types (managed by deploy scripts)

All keys are configurable via CT_CUSTOM_TYPE_* / CT_PRODUCT_TYPE_* env vars.

Payment Flows

Drop-in (Payment Element)

1. Enabler fetches config → loads Stripe SDK → creates Elements + PaymentElement
2. Checkout mounts PaymentElement to DOM
3. On submit: elements.submit() → GET /payments (creates PI) → sdk.confirmPayment() → POST /confirmPayments/:id
4. Webhooks update CT payment with transaction states

Express Checkout

1. Enabler creates ExpressCheckoutElement (with initialAmount)
2. User clicks pay → onPayButtonClick gets session → modal opens
3. User selects address → shippingaddresschange → callbacks update cart
4. User selects shipping → shippingratechange → callbacks update cart + amount
5. User confirms → elements.submit() → GET /payments (with x-express-checkout: true, no shipping on PI) → sdk.confirmPayment() → POST /confirmPayments/:id

BNPL Return Flow

For redirect-based methods (BNPL), Stripe appends payment_intent to MERCHANT_RETURN_URL. Merchant must extract ct_payment_id from PI metadata and pass as paymentReference to CT Checkout SDK.

Connect Deployment (connect.yaml)

• Enabler: applicationType: assets
• Processor: applicationType: service, endpoint /
  • postDeploy: creates custom types + updates Stripe webhook URL
  • preUndeploy: removes custom types (subscription product type, line item type, customer type)

Dev Commands

Processor

cd processor
cp .env.template .env  # fill in values
npm install
npm run build
npm run dev            # local development
npm run test
npm run lint:fix
npm run connector:post-deploy
npm run connector:pre-undeploy

Enabler

cd enabler
cp .env.template .env
npm install
npm run build
npm run dev            # http://127.0.0.1:3000/

Docker (all services + JWT mock server)

docker compose up      # starts JWT server, enabler, processor