commercetools Connect

Architecture Decisions

Table of Contents

• Pattern 1: Pick the application type
• Pattern 2: Price the synchronous contract (service as API Extension)
• Pattern 3: Price the asynchronous contract (event)
• Pattern 4: Combine application types in one connector
• Pattern 5: Is Connect the right fit? (best practices)
• Checklist

Pattern 1: Pick the application type

A service app is just an HTTP endpoint; API Extension is one mode, inbound webhook is another — see service-applications.md. Note that event apps consume commercetools' own Subscription messages only; an external system's changes never arrive as event messages, so "external → commercetools" is always service (reactive) or job (scheduled).

Pattern 2: Price the synchronous contract (service as API Extension)

• Latency is additive. Connection must establish within 1 s; the response limit is 2 s by default, configurable up to 10 s (timeoutInMs); beyond that needs a per-project review. Every millisecond your extension takes is added to the customer's cart/checkout call.
• Availability is coupled. If your extension fails or times out, the commercetools operation fails or stalls. It is applied to all clients, including the Merchant Center.
• Therefore you must decide: fail-open (let the operation proceed on error) or fail-closed (block it), and budget an outbound timeout well under the extension timeout.

Pattern 3: Price the asynchronous contract (event)

• At-least-once delivery. The same message may arrive more than once → you must be idempotent.
• No ordering guarantee. Messages can arrive out of order, especially after retries → never assume "created before updated"; use sequenceNumber (Message) or re-fetch current state.
• Redelivery on non-ack. If you don't acknowledge (Connect: any response other than 102/200/201/202/204), the message is retried. A bug that returns 500 on an unprocessable message becomes an infinite redelivery loop.
• No delivery-time guarantee. Usually seconds, but minutes are possible. Do not use Subscriptions for time-critical paths.

Pattern 4: Combine application types in one connector

deployAs:
  - name: tax-extension
    applicationType: service      # price the cart synchronously at checkout
    endpoint: /service
  - name: tax-committer
    applicationType: event        # commit/void the tax document after the order is placed
    endpoint: /event

Pattern 5: Is Connect the right fit? (best practices)

If a use case fails these, the answer may be "not a Connect app" — say so rather than forcing it.

Checklist

• Connector is stateless, single-responsibility, and fits the runtime timeouts (best practices)
• Each application's type chosen by invocation timing, not domain
• For every service API Extension: latency budget and fail-open/closed stance written down → service-applications.md
• For every service inbound webhook: caller auth and idempotent-upsert strategy written down → service-applications.md
• "External system → commercetools" routed to service (reactive) or job (scheduled), never event
• For every event app: idempotency key and redelivery-safe ack strategy written down → event-applications.md
• Work that doesn't need to block the operation is an event, not a service
• Shared code factored into a shared/ workspace, not duplicated per app

Connect CLI

Step 1. Install the CLI and authenticate

npm install -g @commercetools/cli
commercetools --version
commercetools auth login --client-credentials \
  --client-id <id> --client-secret <secret> --region <region> --project-key <key>

Step 2. Scaffold the connector

commercetools connect init my-connector            # add: --template <name> to start from a template

Add another application to an existing connector later:

commercetools connect application add --type service|event|job --language typescript|javascript|java

Match the route to the endpoint. The platform routes traffic to {connect-url}/{endpoint}. Mount your router at the same base path as the endpoint in connect.yaml (e.g. endpoint: /service ↔ app.use('/service', router)), or all traffic 404s.

Step 3. Pin dependency versions

These are the minimum supported versions for a connector built with this tooling. Pin them; do not fall back to older clients.

npm install \
  @commercetools/platform-sdk@^8 \
  @commercetools/ts-client@^4

• @commercetools/platform-sdk@^8 — the typed API builder (createApiBuilderFromCtpClient).
• @commercetools/ts-client@^4 — the client (ClientBuilder). Do not use the legacy @commercetools/sdk-client-v2.

<dependency>
  <groupId>com.commercetools.sdk</groupId>
  <artifactId>commercetools-sdk-java-api</artifactId>
  <version>19.0.0</version>    <!-- commercetools Java SDK 19 or above -->
</dependency>

• commercetools Java SDK 19+

Step 4. Develop and test locally

Run everything through the CLI so local behavior matches the platform:

commercetools connect application build     # build
commercetools connect application start     # run locally
commercetools connect application test      # run the test suite
commercetools connect validate              # validate connect.yaml + apps before shipping
commercetools connect bundle                # bundle the applications

Step 5. Stage, preview, publish, and deploy

# Register the staged (private) connector from your git repo:
commercetools connect connectorstaged create \
  --repository-url <url> --repository-tag <tag> --creator-email <email> --name <name>
commercetools connect connectorstaged describe --key <connector-key>
commercetools connect connectorstaged list

# Preview to test the staged connector (needs isPreviewable):
commercetools connect connectorstaged preview \
  --key <connector-key> --deployment-key <dep-key> --region <region>

# Publish so it can run in production:
commercetools connect connectorstaged publish --key <connector-key>
# Public marketplace listing only — certification:
commercetools connect connectorstaged certify --key <connector-key>

# Deploy / install into a project (this IS installation):
commercetools connect deployment create --connector-key <key> --region <region> --type preview|sandbox|production
commercetools connect deployment describe --key <deployment-key>
commercetools connect deployment logs --key <deployment-key> --application service --startDate <iso> --endDate <iso>
commercetools connect deployment redeploy --key <deployment-key> --configuration KEY=value
commercetools connect deployment list
commercetools connect deployment delete --key <deployment-key>

Flag names and exact options can evolve — confirm with commercetools connect <command> --help and the Connect CLI docs. Source of truth for platform behavior: docs.commercetools.com/connect.

Deployment & Installation

Table of Contents

• Pattern 1: The connect.yaml configuration contract
• Pattern 2: Deployment types and lifecycle
• Pattern 3: Regions
• Pattern 4: Install and redeploy
• Pattern 5: Certification for public connectors
• Pattern 6: The required connector README
• Pattern 7: Troubleshooting
• Checklist

Pattern 1: The connect.yaml configuration contract

• Give every key a clear description — it's what the installer reads in the Merchant Center.
• Provide sensible defaults for standardConfiguration where possible to reduce install friction.
• Put secrets in securedConfiguration (security.md).
• Prefer inheritAs.apiClient.scopes so the platform auto-generates the API client at install — the installer doesn't have to create one.

Pattern 2: Deployment types and lifecycle

Pattern 3: Regions

Pattern 4: Install and redeploy

Pattern 5: Certification for public connectors

Pattern 6: The required connector README

Every connector built with this skill ships a README. It is the install contract for a human operator and a certification artifact. It must state:

• Fail-open vs fail-closed stance per use case — what happens to carts/orders/messages when the external dependency is down (service-applications.md, event-applications.md).
• Required scopes — the exact inheritAs.apiClient.scopes (or the minimal pre-created client scopes), never "admin" (security.md).
• Configuration table — every connect.yaml key (standard and secured), its meaning, whether required, and its default.
• Poison-message / replay runbook — detection, DLQ/containment, and replay procedure (observability-operations.md).

Pattern 7: Troubleshooting

• Deployment failed at postDeploy → a non-zero exit rolls back. Check deployment logs; common causes: missing required config, invalid external credentials (validate them in postDeploy so this is explicit), or an Extension/Subscription key collision.
• Carts/orders suddenly failing after deploy → a fail-closed extension whose endpoint is erroring, or a dangling Extension after an undeploy that didn't clean up (lifecycle-scripts.md). Check the extension destination and /status.
• Messages redelivering forever → a handler returning non-2xx on an unprocessable message (event-applications.md, Pattern 2).
• First request after idle is slow → sandbox cold-start (~15 s); use production for warmed instances.
• Changes not taking effect → Extension/Subscription changes can take up to a minute (eventual consistency); deployment can take ~15 minutes.

Checklist

• commercetools connect validate passes before staging; staged/previewed/published/deployed via the CLI
• Every configuration key has a clear description; sensible defaults on standardConfiguration; secrets in securedConfiguration
• Least-privilege scopes via inheritAs.apiClient.scopes (or documented minimal set)
• Deployed in the same region as the target project
• Redeploy (not delete/recreate) used for config changes; postDeploy is idempotent
• Connector README documents: fail-open/closed stance, required scopes, full configuration table, poison-message/replay runbook
• For public listing: certification requirements reviewed (private connectors skip this)

Event Applications (Subscription Handlers)

Table of Contents

• Contract facts (verified)
• Pattern 1: Validate the envelope before processing
• Pattern 2: Acknowledge correctly — redelivery is driven by your status code
• Pattern 3: Filter message types and ignore the rest
• Pattern 4: Idempotency under at-least-once delivery
• Pattern 5: Re-fetch by ID, never trust the payload
• Pattern 6: Self-change filtering
• Pattern 7: Register the Pub/Sub subscription destination
• Checklist

Contract facts (verified)

• At-least-once delivery, no ordering guarantee, no delivery-time guarantee.
• The payload arrives wrapped in the Google Cloud Pub/Sub push envelope, and message.data is base64-encoded. All Google Cloud Platform event payload message.data is base64-encoded (verified: Connect — locally test an event app) — the wrapper is { "message": { "data": "<base64>" } }. The base64 is the Pub/Sub transport, not something commercetools adds; the commercetools notification underneath is plain JSON. Decode it before processing (Pattern 1).
• Ack by status code (Connect event apps): the broker retries unless the app responds 102, 200, 201, 202, or 204. Too many negative acks trigger push backoff.
• Event acknowledgement timeout: 10 seconds. Application request times out after 5 minutes; the broker retains unacknowledged messages for 7 days.
• Delivery identity (for dedup comparisons and logging, not storage): for notificationType: "Message" the resource.id + sequenceNumber; for Change payloads (ResourceCreated/Updated/Deleted) the resource.id + version.
• payloadNotIncluded: if the message exceeds the queue's size limit (often 256 KB) the payload is omitted — you must re-fetch the resource by ID.

Pattern 1: Validate the envelope before processing

const msg = JSON.parse(Buffer.from(req.body.message.data, 'base64').toString());
await process(msg.resource.id);   // throws on any malformed/empty envelope → 500 → redelivered forever

function decodeEnvelope(body: unknown): SubscriptionMessage {
  const message = (body as any)?.message;
  if (!message || typeof message.data !== 'string') {
    throw new BadEnvelope('missing Pub/Sub message data');
  }
  let parsed: SubscriptionMessage;
  try {
    parsed = JSON.parse(Buffer.from(message.data, 'base64').toString().trim());   // base64 → JSON
  } catch {
    throw new BadEnvelope('cannot parse message data');
  }
  if (!parsed.resource?.typeId || !parsed.resource?.id || !parsed.notificationType) {
    throw new BadEnvelope('missing resource reference or notificationType');
  }
  return parsed;
}

Decide deliberately what a malformed envelope returns. A truly un-parseable envelope will never become valid on retry, so returning a 2xx (ack-and-drop, logged) avoids a redelivery loop; some teams prefer a 4xx plus monitoring. Either is defensible — an un-acked 5xx loop is not.

Pattern 2: Acknowledge correctly — redelivery is driven by your status code

This is the single most important event-app decision. The broker redelivers on any non-ack response.

if (!isSupported(message)) {
  throw new CustomError(400, `Resource type ${message.resource.typeId} not supported`);
}

try { await handle(message); } catch (e) { logger.error(e); }   // always falls through to 200
res.status(200).send();

try {
  await handle(message);
  res.status(204).send();                 // handled (or intentionally ignored)
} catch (err) {
  if (isTransient(err)) { res.status(503).send(); return; }   // let the broker retry
  logger.error({ correlationId, err }, 'permanently unprocessable message');
  res.status(200).send();                 // ack; alert/DLQ instead of looping
}

Pattern 3: Filter message types and ignore the rest

Subscribe narrowly, then branch on type and ack anything you don't handle.

switch (message.resource.typeId) {
  case 'order':
    if (isOrderConfirmed(message)) await syncOrder(message.resource.id);
    break;                                  // anything else about orders: ack, do nothing
  default:
    break;                                  // includes the platform's subscription test message
}
res.status(204).send();

Pattern 4: Idempotency under at-least-once delivery

const seen = new Set<string>();             // lost on restart; not shared across instances
if (seen.has(message.id)) return;
seen.add(message.id);

// Let the target system's own idempotency decide: does it already have this resource?
const existing = await external.findByOrderId(orderId);
if (existing) { logger.info({ orderId }, 'already synced; skip'); return; }
await external.create(/* ... */);   // or upsert by a stable key, so a re-run is a no-op

Pattern 5: Re-fetch by ID, never trust the payload

const order = await getOrderById(message.resource.id);   // current truth
if (order.orderState !== 'Confirmed') return;            // re-check against live state

Pattern 6: Self-change filtering

If your handler writes back to commercetools (e.g. sets a custom field on the order), that write can emit a message your subscription receives — a loop.

Pattern 7: Register the Pub/Sub subscription destination

const destination = {
  type: 'GoogleCloudPubSub',
  topic: process.env.CONNECT_GCP_TOPIC_NAME,
  projectId: process.env.CONNECT_GCP_PROJECT_ID,
};

This skill targets GCP-hosted Connect deployments, where the injected destination is Google Cloud Pub/Sub. Don't hardcode a connection string for another broker — always build the destination from the injected CONNECT_GCP_* vars.

Checklist

• Pub/Sub envelope decoded (base64 message.data) and structurally validated (→ JSON → resource ref → notificationType) before processing
• Status codes follow the ack table: 2xx for handled/irrelevant, non-2xx only for retryable failures
• No 4xx/5xx on unsupported-but-subscribed types (no redelivery loop); no blanket error-swallowing (no silent loss)
• Reprocessing is a no-op via stateless means (target's own idempotency, re-fetch-and-re-check, or upsert by stable key) — no local dedup store
• Handler re-fetches the resource by ID; handles payloadNotIncluded
• Self-change filtering prevents write-back loops
• Subscription registers only the needed message types; destination built from the injected CONNECT_GCP_* vars
• Processing stays within the 10 s ack timeout (offload long work; ack fast)

Backend integration

Table of contents

• Server-side session creation (BFF)
• Creating the Order after payment
• Post-purchase: capture, refund, cancel
• Webhook reconciliation
• Who creates the Payment, revisited

Server-side session creation (BFF)

A single BFF endpoint does the three server steps and returns the session:

// POST /api/checkout/session  — returns { sessionId, processorUrl, enablerUrl }
export async function createCheckoutSession(req, res) {
  // 1. Verify the cart belongs to this user (IDOR guard) — fetch it and compare
  //    customerId / anonymousId to the authenticated caller before trusting cartId.
  const cartId = req.session.cartId;

  const token = await getManageSessionsToken();   // client_credentials, manage_sessions:{projectKey}

  // 2. Ensure the cart is payable: recalculate and confirm a non-zero total
  //    (the processor rejects a €0 cart — see contract pitfall 3).

  // 3. Create the Checkout Session (cartRef + processor-matching metadata)
  const r = await fetch(`https://session.${region}.commercetools.com/${projectKey}/sessions`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      cart: { cartRef: { id: cartId } },
      metadata: { applicationKey: APP_KEY },   // or { processorUrl } — what the connector expects
    }),
  });
  const session = await r.json();
  res.json({ sessionId: session.id, processorUrl: PROCESSOR_URL, enablerUrl: ENABLER_URL });
}

Notes that matter:

• Create the session as late as possible — when the user reaches the payment step — because sessions expire. Don't mint it at cart creation.
• Verify cart ownership before creating a session (IDOR): fetch the cart and compare its customerId/anonymousId to the authenticated user. See the BFF responsibilities.
• The browser never needs projectKey/region as public env vars — return them from this endpoint alongside sessionId.

Creating the Order after payment

1. The cart has shipping address, shipping method, and billing address (if required) — and the Payment is linked to the cart (the processor does the link via addPayment; confirm cart.paymentInfo.payments is populated).
2. Payment authorization is complete for synchronous flows. For async PSPs, wait for the webhook to move the transaction to Success before committing (see reconciliation).
3. You're using the latest cart version.
4. Business validations (stock, min order value) pass.

// POST /api/checkout/place-order
const order = await apiRoot.orders().post({
  body: {
    cart: { typeId: 'cart', id: cartId },
    version: cartVersion,          // must be current
    orderNumber,                   // unique, pre-generated → idempotency
  },
}).execute();

// server-side, inside the order-creation route
const { body: cart } = await apiRoot.carts().withId({ ID: cartId }).get().execute()
// cart.version is now current — use it, not the client-supplied version
const order = await apiRoot.orders().post({ body: {
  cart: { typeId: 'cart', id: cartId },
  version: cart.version,   // ← always freshly fetched
  orderNumber,
}}).execute()

Order-creation timing — pick one and be consistent:

• Authorize → create Order → capture on fulfillment (common for physical goods): the connector authorizes during submit(); you create the Order on a successful authorization, then capture later.
• Immediate capture → create Order (digital goods): the connector captures during submit() (STRIPE_CAPTURE_METHOD=automatic); you create the Order once the Charge is Success.

If the cart total changed between authorization and order creation (discount expired, tax shift), don't silently proceed — cancel the authorization and re-authorize for the new amount, or surface the new total for confirmation. The processor/PSP handles the money; you orchestrate the decision.

Post-purchase: capture, refund, cancel

• Direct-connector path (this skill): the processor exposes its own operation routes for capture/refund/cancel. The template states "The processor application exposes additional API endpoints for initiating the capture, refund, and cancellation transactions." Call those processor routes (session- or service-authenticated per the connector) from your back-office/fulfillment backend. The processor talks to the PSP and writes the resulting Charge / Refund / CancelAuthorization transaction onto the Payment.
• Checkout-product path (not this skill): if the Payment was created by the hosted Checkout product, use the Checkout Payment Intents API (manage_checkout_payment_intents scope) to capture/refund/reverse/cancel. The Payment Intents API works only for payments created by Checkout — do not reach for it on the direct-connector path.

Webhook reconciliation

• Treat a UI "success" as provisional; gate Order creation (or order confirmation) on the transaction reaching Success when the PSP is async.
• If a transaction is stuck Pending, suspect the webhook (endpoint registered, points at the processor, secret matches — see the provider reference).
• Make handling idempotent: the same webhook may arrive twice.

The return URL race condition

// return URL page — order creation with webhook-wait polling
const MAX_ATTEMPTS = 10
const GAP_MS = 1500   // 10 × 1.5s = 15s total — enough for any healthy webhook delivery

for (let i = 0; i < MAX_ATTEMPTS; i++) {
  const res = await fetch('/api/orders/create', { method: 'POST', body: ... })
  if (res.ok) return await res.json()            // gate opened, order created
  if (res.status !== 422) throw new Error(...)   // hard error — don't retry
  if (i < MAX_ATTEMPTS - 1) await sleep(GAP_MS) // 422 = still Pending, wait for webhook
}
throw new Error('Payment not confirmed after webhook timeout — check Stripe webhook delivery')

Who creates the Payment, revisited

Checklist

• Session/cart/token creation is server-side; browser gets only sessionId + processor/enabler URLs
• Cart ownership verified before session creation (IDOR guard)
• Order created from cart with server-refetched version (never the client-supplied version — the processor bumps the cart via addPayment and makes any client-held version stale) + unique pre-generated orderNumber (idempotent)
• Order creation gated on authorization complete (and on webhook Success for async PSPs)
• Return URL handler polls for Order creation (retries on 422 with a gap) rather than firing once — avoids the return-URL/webhook race condition
• orderNumber is pre-generated and reused across retries so polling can't double-create
• Capture/refund/cancel go through the processor's operation routes (not the Payment Intents API, which is Checkout-only)
• Post-order side effects (email, ERP) driven off the OrderCreated Subscription, not the request path
• Backend does not create Payment objects (the processor owns them)

Test-driving the backend

Hard rule: no implementation code before its test. Install Vitest and write the first failing test before writing any function body. If you find yourself with working code and no test, you have skipped this step — stop, write the test (it may already pass, which means it's now a regression guard rather than a design tool, but it still must exist), and confirm it would fail if the behavior were removed before continuing.

npm install --save-dev vitest @vitest/coverage-v8
# add to package.json scripts: "test": "vitest run"
npm test   # should exit 0 with "no test files found" — harness is live

This "test": "vitest run" is right for the BFF/storefront (which you run yourself). But for a custom connector, prefer Jest — the Connect platform validates npm test at publish and its examples (and the connector templates) use Jest. If you do use Vitest, run each app's test through a wrapper that calls Vitest with a fixed arg list (Vitest aborts on unknown CLI options), and give every app — including the assets enabler — a test script. See stripe.md → "Prefer Jest for connector apps".

The loop

For each behavior, smallest first:

1. Red — write one test that names the behavior and asserts the outcome. Run it. It must fail because the behavior is missing, not because the import is wrong or the mock isn't wired — a test that passes before you've written anything, or errors for a boring reason, is testing nothing. Read the failure and confirm it's the failure you expected.
2. Green — write the least code that makes it pass. Resist generalizing; the next test will tell you what to generalize.
3. Refactor — clean up with the test as a safety net.

Where to draw the test boundary

• Mock the outbound boundary (the processor's operation routes, the Sessions API, the PSP, the CT Orders/Payments API client) and assert on what your code decided to do: which endpoint it called, with what body, in what order, and what it did with the response. These tests are fast, deterministic, and run with no deployment and no secrets — so they run on every commit.
• Don't mock your own orchestration logic — that's the thing under test.
• Don't try to assert the PSP actually charged a card here. That's the job of the full-flow integration test (integration-test.md), which runs against a real deployed connector with test cards. Unit tests prove your decisions; the integration test proves the wiring.

What to test, per backend piece

BFF session creation

• Happy path: an owned, non-zero cart yields a sessionId and the processor/enabler URLs. This is the baseline the guards below deviate from.
• IDOR guard: a session is created only when the cart belongs to the caller. Test the rejection path — a cart whose customerId differs from the authenticated user must not produce a session. This is the test that matters most and the one most likely to be missing.
• Secrets stay server-side: the object returned to the browser contains sessionId, processorUrl, enablerUrl and nothing else — assert the response has no access_token, no client secret. A snapshot or explicit key-set assertion catches a careless res.json(session) that leaks the whole token response.
• Non-zero cart: a €0 cart is refused before a session is minted (the processor would reject it anyway — contract pitfall 3).

import { describe, it, expect, vi } from 'vitest';
import { createCheckoutSession } from '../bff/session';

describe('BFF session creation', () => {
  it('refuses to create a session for a cart the caller does not own (IDOR)', async () => {
    const ctCarts = { get: vi.fn().mockResolvedValue({ id: 'cart-1', customerId: 'someone-else' }) };
    const sessionsApi = { create: vi.fn() };

    await expect(
      createCheckoutSession({ cartId: 'cart-1', user: { customerId: 'me' }, ctCarts, sessionsApi }),
    ).rejects.toThrow(/forbidden|ownership/i);

    expect(sessionsApi.create).not.toHaveBeenCalled();   // the real assertion: no session was minted
  });

  it('returns only sessionId + processor/enabler URLs to the browser', async () => {
    const ctCarts = { get: vi.fn().mockResolvedValue({ id: 'cart-1', customerId: 'me', totalPrice: { centAmount: 1999 } }) };
    const sessionsApi = { create: vi.fn().mockResolvedValue({ id: 'sess-1', accessToken: 'SECRET' }) };

    const out = await createCheckoutSession({ cartId: 'cart-1', user: { customerId: 'me' }, ctCarts, sessionsApi });

    expect(out).toEqual({ sessionId: 'sess-1', processorUrl: expect.any(String), enablerUrl: expect.any(String) });
    expect(JSON.stringify(out)).not.toContain('SECRET');   // no token leaks to the client
  });
});

Order creation

• Happy path: an owned cart whose linked Payment has a Success transaction creates exactly one Order at the current cart version and flips cartState to Ordered. This is the contract; the gates below are when it must not fire.
• Gated on authorization: with no Success transaction on the linked Payment, placeOrder must not call ctOrders.create. For an async PSP, "authorization complete" means the webhook moved it to Success — so the gate is the same test with the transaction still Pending.
• Declined payment never commits: a Failure transaction (card declined, insufficient funds — the most common real-world error path) must block Order creation just like Pending does, and the caller should get a clear decline back, not a generic 500. This is distinct from Pending: Pending is "not yet," Failure is "no" — and an Order built on a declined Payment is the worst outcome, an unpaid fulfilled order.
• Idempotent on orderNumber: two calls with the same pre-generated orderNumber create at most one Order. Simulate the CT "duplicate orderNumber" rejection on the second call and assert your code treats it as success (returns the existing Order), not as an error to retry into a third attempt.
• Uses the current cart version: a stale version is rejected; assert you refetch/propagate the version rather than reusing a cached one.

it('creates exactly one Order from an authorized cart and marks it Ordered (happy path)', async () => {
  const created = { id: 'order-1', orderNumber: 'ord-1', cartState: 'Ordered' };
  const ctOrders = { create: vi.fn().mockResolvedValue(created) };
  const payment = { transactions: [{ type: 'Authorization', state: 'Success' }] };  // authorized

  const order = await placeOrder({ cartId: 'c1', cartVersion: 3, orderNumber: 'ord-1', payment, ctOrders });

  expect(ctOrders.create).toHaveBeenCalledOnce();
  expect(ctOrders.create).toHaveBeenCalledWith(expect.objectContaining({ orderNumber: 'ord-1', version: 3 }));
  expect(order.cartState).toBe('Ordered');
});

it('does not create an Order until a Success transaction exists', async () => {
  const ctOrders = { create: vi.fn() };
  const payment = { transactions: [{ type: 'Authorization', state: 'Pending' }] };  // async PSP, not settled

  await expect(placeOrder({ cartId: 'c1', cartVersion: 3, orderNumber: 'ord-1', payment, ctOrders }))
    .rejects.toThrow(/not authorized|pending/i);
  expect(ctOrders.create).not.toHaveBeenCalled();
});

it('refuses to create an Order on a declined payment, surfacing the decline (error path)', async () => {
  const ctOrders = { create: vi.fn() };
  const payment = { transactions: [{ type: 'Authorization', state: 'Failure' }] };  // card declined

  await expect(placeOrder({ cartId: 'c1', cartVersion: 3, orderNumber: 'ord-1', payment, ctOrders }))
    .rejects.toMatchObject({ code: 'PaymentDeclined' });   // a clear decline, not a generic 500
  expect(ctOrders.create).not.toHaveBeenCalled();          // never an unpaid Order
});

it('is idempotent: a duplicate orderNumber returns the existing Order, not an error', async () => {
  const existing = { id: 'order-1', orderNumber: 'ord-1' };
  const ctOrders = {
    create: vi.fn().mockRejectedValueOnce({ statusCode: 400, code: 'DuplicateField', field: 'orderNumber' }),
    getByOrderNumber: vi.fn().mockResolvedValue(existing),
  };
  const payment = { transactions: [{ type: 'Authorization', state: 'Success' }] };

  const order = await placeOrder({ cartId: 'c1', cartVersion: 3, orderNumber: 'ord-1', payment, ctOrders });
  expect(order).toEqual(existing);     // a retry converges on the one Order, never a second
});

it('is idempotent: "cart not in active state" (cartState=Ordered) also returns the existing Order', async () => {
  // After the first order creation succeeds, CT flips cartState → Ordered.
  // A second POST /orders then fails with InvalidOperation "not in active state"
  // *before* CT checks the orderNumber, so DuplicateField is never raised.
  // The handler must also catch this case and return the existing Order.
  const existing = { id: 'order-1', orderNumber: 'ord-1' };
  const ctOrders = {
    create: vi.fn().mockRejectedValueOnce({
      statusCode: 400,
      body: { errors: [{ code: 'InvalidOperation', message: 'The cart is not in active state.' }] },
    }),
    getByOrderNumber: vi.fn().mockResolvedValue(existing),
  };
  const payment = { transactions: [{ type: 'Authorization', state: 'Success' }] };

  const order = await placeOrder({ cartId: 'c1', cartVersion: 4, orderNumber: 'ord-1', payment, ctOrders });
  expect(order).toEqual(existing);
});

Post-purchase capture / refund / cancel

• Routes through the processor, never the Payment Intents API: assert the processor's operation route was called and that no Payment Intents endpoint (/checkout/payment-intents, the manage_checkout_payment_intents path) was touched. This is a guardrail test — its job is to fail loudly the day someone "simplifies" it to the wrong API.
• Capture idempotency: one Charge per PSP interactionId; a retried capture with the same interaction id doesn't double-charge.
• Partial refund only when configured/allowed: a partial refund above the captured amount is rejected; multiple partial refunds sum correctly up to the captured total.

it('routes capture through the processor, not the Payment Intents API', async () => {
  const processor = { capture: vi.fn().mockResolvedValue({ ok: true }) };
  const paymentIntents = { capture: vi.fn() };   // the wrong API — must stay untouched

  await capturePayment({ paymentId: 'pay-1', amount: { centAmount: 1999 }, processor, paymentIntents });

  expect(processor.capture).toHaveBeenCalledOnce();
  expect(paymentIntents.capture).not.toHaveBeenCalled();   // guardrail against the Checkout-only API
});

it('does not double-charge on a retried capture (idempotent by interactionId)', async () => {
  const processor = { capture: vi.fn().mockResolvedValue({ interactionId: 'pi_123' }) };
  const seen = new Set<string>();

  await capturePayment({ paymentId: 'pay-1', interactionId: 'pi_123', processor, seen });
  await capturePayment({ paymentId: 'pay-1', interactionId: 'pi_123', processor, seen });   // retry

  expect(processor.capture).toHaveBeenCalledOnce();
});

Webhook reconciliation

This is where async PSPs live, and it's the piece most painful to exercise by hand because it depends on a signed event arriving — possibly twice. Tests pay off the most here.

• Idempotent on redelivery: the same webhook event id applied twice leaves the Payment in the same state and creates at most one transaction. PSPs will redeliver; assert it.
• Signature/verification is enforced: a tampered or unsigned payload is rejected before any state change. (For a custom processor you own this; for the public connector, test your own handler's gate if you have one in front.)
• Drives the gate the Order waits on: after the webhook moves the transaction to Success, the Order-creation gate that was closed in the Order test now opens. A test that asserts "stuck Pending → no Order; webhook arrives → Order proceeds."

it('is idempotent when the PSP redelivers the same event', async () => {
  const ctPayments = { addTransaction: vi.fn().mockResolvedValue({}) };
  const processed = new Set<string>();
  const event = { id: 'evt_1', type: 'payment_intent.succeeded', paymentId: 'pay-1' };

  await handleWebhook({ event, ctPayments, processed });
  await handleWebhook({ event, ctPayments, processed });   // redelivery

  expect(ctPayments.addTransaction).toHaveBeenCalledOnce();
});

A note on not over-testing

Checklist

Gate: do not proceed to Step 5 (integration test / verification) until every box below is checked and npm test exits 0 with no secrets in the environment.

• Vitest installed and npm test runs before the first line of implementation — not after
• Each backend behavior was written test-first: a failing test, confirmed to fail for the right reason, then the code; no function body existed before its test
• Outbound boundary (processor, Sessions/Orders API, PSP) is mocked behind a port; orchestration logic is not mocked
• Happy path pinned per piece: owned cart → session; Success → exactly one Order marked Ordered; capture/refund recorded
• BFF: IDOR rejection tested; response asserted to carry no secrets; €0 cart refused
• Order: gated on a Success transaction (async = webhook); declined (Failure) payment refused with a clear decline (not a generic 500); idempotent on orderNumber; current cart version used
• Capture/refund/cancel: routed through the processor with the Payment Intents API asserted untouched; capture idempotent by interactionId
• Webhook: idempotent on redelivery; signature verification enforced before any state change; opens the Order gate
• npm test exits 0 with no deployment/secrets in the environment (those belong to the integration test)

From requirements to config

Table of contents

• The connect.yaml envelope
• The mapping
• How to present the result
• Worked example (Stripe)
• Pitfalls in the config itself

The connect.yaml envelope

deployAs:                              # required — array of the connector's applications
  - name: processor                    # required — must match the application's folder name in the repo
    applicationType: service           # service | event | job | merchant-center-custom-application | merchant-center-custom-view | assets
    endpoint: /processor               # required for service/event/job; omit for assets and the MC types
    properties:
      schedule: '*/5 * * * *'          # job type only — cron expression
    scripts:                           # optional — only if the app installs Extensions/Subscriptions
      postDeploy: npm run connector:post-deploy
      preUndeploy: npm run connector:pre-undeploy
    configuration:                     # optional (omit for assets)
      standardConfiguration:           # non-secret env vars; each: key, description, required, default?
        - key: CTP_PROJECT_KEY
          description: ...
          required: true
          default: 'default-key'       # default? is allowed here only
      securedConfiguration:            # secrets; each: key, description, required — NO default
        - key: CTP_CLIENT_SECRET
          description: ...
          required: true
inheritAs:                             # optional — config/scopes shared across all applications
  configuration:
    standardConfiguration: [...]
    securedConfiguration: [...]
  apiClient:
    scopes:                            # for auto-generated API Client credentials
      - manage_payments

inheritAs.apiClient and self-supplied CTP_CLIENT_ID/CTP_CLIENT_SECRET are mutually exclusive — declaring both is a deploy/install-time conflict. Pick one credential model, not both:

• Auto-generated (recommended): declare inheritAs.apiClient.scopes and let Connect mint the credentials and inject them. Then remove the CT-client keys from your config — CTP_CLIENT_ID, CTP_CLIENT_SECRET, and CTP_SCOPE from securedConfiguration, and CTP_PROJECT_KEY from standardConfiguration — Connect injects all of these at runtime, and leaving them declared causes a deploy conflict.
• Self-supplied: declare CTP_CLIENT_ID/CTP_CLIENT_SECRET in securedConfiguration and drop the inheritAs.apiClient block; the deployer provides the values.

The securedConfiguration example below shows the self-supplied half; if you keep inheritAs.apiClient, remove those CT-client keys.

my-stripe-connector/
├── connect.yaml          ← here, and only here
├── processor/            ← name: processor, applicationType: service
└── enabler/              ← name: enabler, applicationType: assets

The mapping

How to present the result

Give the user four things, not a vague pointer:

1. A filled standardConfiguration block with the chosen values inline.
2. The securedConfiguration keys they must set themselves (names only — never fabricate secret values).
3. The API-client scopes the connector needs (at minimum: manage_payments, view_sessions; add manage_orders if the connector creates/links Carts or Orders). Two traps here:
   • Don't request manage_project as a shortcut. It's a broad superset that masks which scopes you actually need and over-privileges the connector; it also won't survive a least-privilege review or certification. List the specific scopes.
   • The runtime token scopes must match the declared scopes. Whatever the SDK client requests at token time (e.g. withClientCredentialsFlow({ scopes: [...] })) must be covered by the API client's granted scopes. With auto-generated credentials (inheritAs.apiClient.scopes), requesting a scope you didn't declare — e.g. manage_project — fails token acquisition with invalid_scope (400). Either omit the explicit scopes array (inherit the client's scopes) or request exactly the declared set.
4. A short rationale list: for each non-default or non-obvious key, one line tying it to the requirement it came from. This is what lets the user catch a wrong assumption.

Worked example (Stripe)

# processor — standardConfiguration — values shown are deployment inputs, NOT connect.yaml fields
- key: CTP_PROJECT_KEY
  value: acme
- key: CTP_API_URL
  value: https://api.europe-west1.gcp.commercetools.com      # region
- key: CTP_AUTH_URL
  value: https://auth.europe-west1.gcp.commercetools.com     # region
- key: CTP_SESSION_URL
  value: https://session.europe-west1.gcp.commercetools.com  # region
- key: STRIPE_CAPTURE_METHOD
  value: manual                  # authorize now, capture on shipment → also: create Order on auth, capture later
- key: STRIPE_SAVED_PAYMENT_METHODS_CONFIG
  value: '{"payment_method_save":"enabled"}'   # save cards → requires customerId on the cart
- key: STRIPE_ENABLE_MULTI_OPERATIONS
  value: 'true'                  # partial refunds expected (also enable multicapture in the Stripe account)
- key: STRIPE_COLLECT_BILLING_ADDRESS
  value: auto
- key: MERCHANT_RETURN_URL
  value: https://shop.acme.com/order-complete   # absolute URL w/ scheme
- key: ALLOWED_ORIGINS
  value: https://shop.acme.com,http://localhost:5173   # every browser origin that calls the processor
- key: PAYMENT_INTERFACE
  value: checkout-stripe         # written on the Payment; query payments by this later

# processor — securedConfiguration (user supplies the values)
- key: STRIPE_SECRET_KEY                  # Stripe test/live secret key
- key: STRIPE_WEBHOOK_SIGNING_SECRET      # verifies inbound Stripe webhooks
- key: CTP_CLIENT_ID
- key: CTP_CLIENT_SECRET
- key: CTP_SCOPE                           # required alongside ID/SECRET in the self-supplied model
# plus STRIPE_WEBHOOK_ID (standard) once the webhook endpoint exists

Rationale to hand back:

• STRIPE_CAPTURE_METHOD: manual — they capture on shipment, so authorize at pay time and capture later via the processor; this is also why the Order is created on a successful authorization, not on charge.
• STRIPE_SAVED_PAYMENT_METHODS_CONFIG: enabled — saving cards binds methods to a Customer, so the cart must carry a customerId; anonymous carts won't save.
• STRIPE_ENABLE_MULTI_OPERATIONS: true — partial refunds were required; this also needs multicapture enabled in the Stripe account.
• ALLOWED_ORIGINS / MERCHANT_RETURN_URL — the two values that silently break the browser flow if wrong; both pinned to the real storefront.

Pitfalls in the config itself

• Leaving region URLs at their defaults when the project is in another region → auth/session failures.
• Enabling saved cards without ensuring a customerId on the cart → no methods saved, confusing "why didn't it save" reports.
• Enabling multi-operations in the connector but not in the PSP account → partial capture/refund calls fail at the PSP.
• A bare-host MERCHANT_RETURN_URL or a missing origin in ALLOWED_ORIGINS → the frontend breaks at runtime, not at deploy.

Checklist

• every requirement from Step 1 mapped to a concrete value (no silent defaults left on behavior-changing keys)
• standardConfiguration filled; securedConfiguration listed by name only
• scopes stated; region URLs match the project's region
• rationale line per non-obvious key, tied to its requirement
• capture-mode decision reflected in the Order-creation timing (→ backend-integration.md)

Payment connector contract (provider-agnostic)

Table of contents

• Two URLs you need
• The 8-step flow
• Sessions API: the request body
• Loading the enabler
• Processor routes and auth
• Who owns the Payment object
• Pitfall catalog
• Configuration that breaks the frontend

Two URLs you need

A deployed connector exposes two public URLs (visible in the Merchant Center deployment view, or via the Connect deployments API):

• processor URL — the service app, e.g. https://service-….{region}.commercetools.app. Your frontend points the enabler at it; the enabler calls it; you can call GET /operations/status directly.
• enabler URL — the assets app, e.g. https://assets-….{region}.commercetools.app. You load the enabler JS bundle from here.

The 8-step flow

1. OAuth token            POST {auth}/oauth/token (client_credentials, manage_sessions[+])
2. Cart (non-zero total)  POST {api}/{projectKey}/carts
3. Checkout Session       POST https://session.{region}.commercetools.com/{projectKey}/sessions
4. Warm processor         GET  {processorUrl}/operations/status        (cold-start guard)
5. Load enabler           <script src="{enablerUrl}/connector-enabler.umd.js">  → window.<Global>.Enabler
6. Construct + build       new Enabler({processorUrl, sessionId, onComplete, onError}) → createDropinBuilder('embedded') → build()
7. Mount + wait ready     dropin.mount('#container'); wait for `ready` before enabling Pay
8. Submit                 dropin.submit()  → processor authorizes/charges via PSP, writes the CT Payment

Sessions API: the request body

POST https://session.{region}.commercetools.com/{projectKey}/sessions
Authorization: Bearer <token with manage_sessions>

{
  "cart": { "cartRef": { "id": "<cartId>" } },
  "metadata": { "applicationKey": "<checkout-application-key>" }
}

Two things the docs make non-obvious for the direct-connector path:

• cart.cartRef.id — a reference to an existing cart, not an inline cart (see pitfall 1).
• metadata must identify the processor the session is for. With a Checkout Application configured in the Merchant Center, that is metadata.applicationKey. Some connector deployments instead validate metadata.processorUrl (the processor checks the session's metadata matches its own deployed URL and otherwise returns 401 "Session is not active"). Use whichever the connector expects — if you get a 401 from the processor with a freshly created session, this metadata mismatch is the first thing to check. The provider reference notes which one a given connector wants.

const cartId = session.activeCart?.cartRef?.id;

Loading the enabler

<script src="https://assets-….commercetools.app/connector-enabler.umd.js"></script>
<script>
  const Enabler = window.Connector.Enabler;   // global name is provider-specific
</script>

Then:

const enabler = new Enabler({
  processorUrl,
  sessionId,
  locale: 'en-US',                 // pass the real locale; don't hardcode in prod
  onComplete: (result) => { /* success → redirect to return URL */ },
  onError: (err) => { /* surface err.message / err.code */ },
});

const builder = await enabler.createDropinBuilder('embedded');
const dropin  = await builder.build({ showPayButton: false }); // own your Pay button
dropin.mount('#dropin-container');

Processor routes and auth

• GET /operations/config — public-ish config the enabler reads (publishable key, capture method, billing address setting, merchant return URL, etc.). On a custom connector you own this endpoint; ensure it returns at least the public key and merchantReturnUrl so the enabler can configure the PSP's JS SDK and the redirect. Some PSPs need additional session-authenticated config routes beyond /operations/config (e.g. one that returns the real cart amount/currency to initialize the payment element) — the provider reference documents any extra routes a given connector requires.
• GET /operations/status — health/readiness. Ping it right after session creation to warm a cold container (pitfall 10).
• the payment route (the enabler calls this for you) — see pitfall 8.
• additional operation routes for capture/refund/cancel — not part of the storefront pay flow, but you call them from your backend for post-purchase money movements (→ backend-integration.md).

Who owns the Payment object

Pitfall catalog

Each pitfall below cost real debugging time. Treat them as pre-flight checks.

1. Session body requires cartRef, not an inline cart

2. Session metadata must match what the processor expects

3. Cart must have a non-zero total

{
  "currency": "EUR",
  "taxMode": "ExternalAmount",
  "customLineItems": [{
    "name": { "en": "Test item" },
    "quantity": 1,
    "money": { "currencyCode": "EUR", "centAmount": 1999 },
    "slug": "test-item",
    "externalTaxRate": { "name": "test", "amount": 0.0, "country": "DE" }
  }]
}

4. Stale CT API Extension returns 502 on cart updates

5. Load the enabler via UMD script tag, not dynamic ES import()

6. MERCHANT_RETURN_URL must be an absolute URL with a scheme

7. Wait for the enabler ready event before submit()

8. The payment-creation route is GET, not POST

9. Processor auth header is X-Session-Id, not Bearer

10. Processor cold-start 504

11. Raw-body webhook parsing can reject empty POST bodies on all routes

12. Deferred-intent: create the PSP intent inside submit(), not at mount time

13. ConcurrentModification on Order creation — cart version is always stale from the client

"Object <cartId> has a different version than expected. Expected: 1 - Actual: 3."

const { body: cart } = await apiRoot.carts().withId({ ID: cartId }).get().execute()
// use cart.version — never the client-supplied value

Do not try to work around this by passing the version from the return URL query string or sessionStorage — those are just as stale. The only reliable source is a fresh GET.

14. Return URL fires before the webhook — Order creation gets a 422

const MAX_ATTEMPTS = 10
const GAP_MS = 1500

for (let i = 0; i < MAX_ATTEMPTS; i++) {
  const res = await fetch('/api/orders/create', { method: 'POST', body: JSON.stringify({ cartId, cartVersion, orderNumber }) })
  if (res.ok) return await res.json()
  if (res.status !== 422) throw new Error(await res.text())   // hard error — stop
  if (i < MAX_ATTEMPTS - 1) await new Promise(r => setTimeout(r, GAP_MS))
}
throw new Error('Webhook timeout — check processor webhook secret and Stripe dashboard delivery log')

15. Order creation returns 400 "cart is not in active state" on idempotent retry

const isDuplicate = err?.statusCode === 400 &&
  err?.body?.errors?.some((e: any) => e.code === 'DuplicateField' && e.field === 'orderNumber');
const isCartOrdered = err?.statusCode === 400 &&
  err?.body?.errors?.some((e: any) => e.code === 'InvalidOperation' && e.message?.includes('not in active state'));

if (isDuplicate || isCartOrdered) {
  const { body: existing } = await apiRoot.orders().withOrderNumber({ orderNumber }).get().execute();
  return existing;
}

16. The id the webhook records may not be the id the refund route needs

17. /operations/status returns 401 during redeployment

Configuration that breaks the frontend

Webhook events — look up, then select for the use case

1. Look it up. Consult the chosen PSP's official webhook-events documentation for the catalog of event types it emits (each PSP names them differently).
2. Map to the lifecycle this skill cares about. The reconciliation only needs the events that move a commercetools transaction or open the Order gate: authorization succeeded, amount became capturable (authorize-now/capture-later), payment failed/declined, refund settled, and — for production — dispute/chargeback opened. Ignore events that don't change payment state.
3. Select the minimal set for this user's flow. The capture mode, refund policy, and whether disputes must be handled (all gathered in Step 1 / config-from-requirements.md) decide which of the above apply. Example: a charge-now flow with no partial refunds needs the "succeeded" and "refunded" events but not "amount capturable"; a manual-capture flow does need the capturable event. Subscribe to what the use case requires, nothing more.

Register exactly that set when setting up the PSP webhook endpoint (the mechanics of registering are in the provider reference and the deploy guide). If a needed event isn't subscribed, the corresponding transaction silently never finalizes.

Checklist

• processor URL and enabler URL read from config (not hardcoded)
• session created with cartRef + processor-matching metadata; got a sessionId
• cart total is non-zero
• processor warmed via GET /operations/status
• enabler loaded from the UMD bundle; global resolved
• Pay button gated on the ready event; submit() only after
• no stale API Extension pointing at a dead URL
• Payment object found after submit (→ verification.md)
• webhook events selected by looking up the PSP's docs and matching the user's use case (not a hardcoded list) — see Webhook events
• (Custom processor) POST /payments sends body: "{}" — fastify-raw-body v5 rejects empty bodies on all routes

Is a certified connector enough?

• Public connectors — listed in the Connect marketplace, ready to install. Some are built by commercetools (e.g. Adyen, PayPal), some by third parties (e.g. Stripe). If one covers the use case, this is almost always the right choice: install + configure, don't build.
• Organization (custom/private) connectors — deployed for your organization only. These come in two flavors that matter a lot here: a fork of an existing public connector's open-source repo (you extend it), or a connector built from scratch off the payment integration template. Both are commercetools-connect tasks.

Don't hardcode "what's supported" — check it live

1. Run the skill's docs-search step and/or query the commercetools Knowledge MCP for "supported PSPs payment methods payment connectors".
2. Read the live Supported PSPs, Payment Integration Types, and payment methods table: connectors-and-applications.md.
3. Browse the live Connect marketplace for installable connectors and their versions: merchant-center/connect.md. For a third-party connector (e.g. Stripe), its own repo/README is the source of truth for capabilities and config keys.

The fit check

Compare the requirements gathered in Step 1 against what a candidate public connector actually supports. Check each dimension:

The decision ladder

1. Public connector covers everything → install + configure (Step 2). Don't build anything. The common, recommended case.
2. Supported PSP, gap looks like a capability → first prove it isn't config. Most "missing" behaviors on a supported PSP (partial refunds, manual capture, saved cards, layout) are connect.yaml toggles, sometimes paired with a PSP-account setting. If a config closes the gap, you're back at rung 1. → config-from-requirements.md.
3. Supported PSP, genuine gap that config can't close → fork/extend the public connector. Its repo is open source (e.g. stripe/stripe-commercetools-checkout-app); add the missing behavior to your fork and deploy it as an Organization connector. You keep the working processor/enabler contract, the session auth, the Payment-ownership model — and only change the delta. This is far cheaper and safer than rebuilding, and it's a commercetools-connect task (extending an existing connector).
4. No public connector for the PSP at all → build from the payment integration template → commercetools-connect. The from-scratch path, justified only when there's nothing to fork.

Only rungs 3–4 leave this skill (hand off to build/extend); the skill resumes once the resulting connector is deployed. Record the decision, the rung, and the connector version checked in the requirements block — so the rest of the work is grounded in a real, confirmed connector, not an assumed one.

Checklist

• Checked live marketplace + supported-PSPs docs (not memory); cited the connector + version
• PSP, methods, integration type, capabilities, region each compared to the requirements
• Apparent capability gaps re-checked as config (rung 2) before considering any build
• When a public connector exists but has a real gap, chose fork/extend (rung 3) over build-from-scratch
• Decision + rung + connector version recorded: configure (1), config (2), fork (3 → commercetools-connect), or build (4 → commercetools-connect)

Deploy a custom (Organization) connector

The flow

0. connect validate         → run the platform's checks LOCALLY, before staging (fast feedback)
1. connectorstaged create   → registers your repo + tag, returns a connector id
2. connectorstaged publish  → server-side validation (SAST/SCA + connect.yaml), makes it deployable (async)
3. deployment create        → actually runs the connector in your project

Step 0 — Authenticate

Same as the public connector path:

commercetools auth login \
  --client-credentials \
  --client-id <CLIENT_ID> \
  --client-secret <CLIENT_SECRET> \
  --region <region e.g. europe-west1.gcp> \
  --project-key <projectKey>

Step 1 — Stage the connector

commercetools connect connectorstaged create \
  --name "my-connector" \
  --description "Custom Stripe payment connector" \
  --repository-url https://github.com/<org>/<repo>.git \
  --repository-tag <git-tag> \
  --creator-email <your-email> \
  --supported-regions europe-west1.gcp \
  --integration-types psp

Step 2 — Publish

commercetools connect connectorstaged publish --id <id-from-step-1>

• Only --id or --key — there is no --force flag.
• Runs async — Connect clones your repo, validates connect.yaml, and registers the connector. It can take a minute or two. You can check status with connectorstaged describe --id <id>.
• Once status shows published, proceed to step 3.

Publish runs a production-readiness scan — for private connectors too

commercetools connect validate    # connect.yaml + the same class of checks, locally

• No logs or any code/configuration that isn't meant for production. Strip leftover console.log/debug logging, dev-only mocks or fixtures, test scaffolding, commented-out blocks, and local-only config (.env samples, NODE_ENV=development defaults baked into the build). If you forked a public connector (rung 3), this is where forks most often fail — leftover demo/sample code from the template.
• No hardcoded URLs, tokens, credentials, or passwords in code or config — everything sensitive belongs in securedConfiguration and is supplied at deploy time (see config-from-requirements.md).
• No outdated/insecure dependencies, and stateless apps (no in-memory session state — the runtime scales and restarts).

The three scans fail for different reasons — read which one failed

• Image security analysis failed (but SAST/SCA passed) → the finding is in the container base image's OS packages, not your code or your declared dependencies. The base image is chosen by the buildpack from your Node version, so the lever you control is pinning it. Add engines.node to every app's package.json (e.g. "engines": { "node": "20.x" }) so the buildpack selects a maintained, scanned-clean base image instead of a default. A stdlib-style CVE (e.g. a Go stdlib advisory) in this scan is the classic base-image symptom — it is never something in your package.json.
• Runtime-version vs. framework-version trap. Pinning the runtime can collide with a dependency's own engine requirement, and the two fixes can be mutually exclusive. Real example hit in the field: Fastify v5 requires Node 20+, but Fastify v4's transitive deps (fast-uri, fast-json-stringify) carry HIGH-severity CVEs whose only fix is Fastify v5. So "pin Node 18" (image scan) and "downgrade Fastify to v4" (avoid a different finding) cancel out — the working combination was Fastify v5 + Node 20. When the image scan and the SCA scan seem to pull in opposite directions, check the framework's supported-Node matrix before downgrading anything; the fix for a dependency CVE is almost always to upgrade, not downgrade (downgrading lands you on the vulnerable version).
• SCA failed → a declared dependency (in some package-lock.json in the repo) has a known CVE. Note the File field in each finding — it tells you which lockfile. If it points at a folder that isn't a connector app (see "Keep the repo to connector apps only" below), the fix is removing that folder, not upgrading.

Keep the repo to connector apps only — sibling folders poison SCA

commercetools connect connectorstaged describe --id <id>

Step 3 — Deploy

Once published, deploy it into your project with your config:

commercetools connect deployment create \
  --region <region> \
  --connector-id <id-from-step-1> \
  --key <your-deployment-key> \
  --type sandbox \
  --configuration 'processor.CTP_PROJECT_KEY=<value>' \
  --configuration 'processor.CTP_CLIENT_ID=<value>' \
  --configuration 'processor.CTP_AUTH_URL=<value>' \
  --configuration 'processor.CTP_API_URL=<value>' \
  --configuration 'processor.CTP_SESSION_URL=<value>' \
  --configuration 'processor.CTP_CHECKOUT_URL=<value>' \
  --configuration 'processor.CTP_JWKS_URL=<value>' \
  --configuration 'processor.CTP_JWT_ISSUER=<value>' \
  --configuration 'processor.STRIPE_PUBLISHABLE_KEY=<value>' \
  --configuration 'processor.MERCHANT_RETURN_URL=<value>' \
  --configuration 'processor.ALLOWED_ORIGINS=<value>'

  --configuration 'processor.CTP_CLIENT_SECRET=<value>' \
  --configuration 'processor.STRIPE_SECRET_KEY=<value>' \
  --configuration 'processor.STRIPE_WEBHOOK_SIGNING_SECRET=<value>'

The deployment must include every application declared in connect.yaml — including the assets enabler, even though it takes no config. If you build the deployment draft by hand (e.g. via the REST API) and list only processor, the deploy may appear to succeed but is malformed: the enabler never deploys (no enabler URL is produced), and a later redeploy fails with the confusing DeploymentApplicationDoNotBelong — "deployment does not include application: 'enabler'". Include the enabler with empty config arrays: { "applicationName": "enabler", "standardConfiguration": [], "securedConfiguration": [] }. The CLI's deployment create handles this for you; raw API/scripted drafts are where this bites.

Step 4 — Get the URLs

commercetools connect deployment describe --key <your-deployment-key>

Step 5 — Register the Stripe webhook

After you have the processor URL, go to the Stripe dashboard and register the webhook:

1. Stripe Dashboard → Developers → Webhooks → Add endpoint

2. Endpoint URL: {processorUrl}/stripe/webhooks
3. Subscribe to the events this user's flow needs — don't copy a fixed list. Look up Stripe's webhook-event catalog and select per the use case, as described in connector-contract.md → Webhook events. (For a typical Stripe flow that often means events like payment_intent.succeeded, payment_intent.amount_capturable_updated for manual capture, payment_intent.payment_failed, and charge.refunded — but confirm against Stripe's current docs and the user's capture/refund/dispute requirements.)
4. Copy the signing secret (whsec_…)
5. Update the deployment's secured config via redeploy — there is no deployment update CLI command, and the Connect REST API does not accept a setApplicationConfiguration action (only redeploy is a valid discriminator):

   commercetools connect deployment redeploy \
     --key <your-deployment-key> \
     --configuration 'processor.STRIPE_WEBHOOK_SIGNING_SECRET=<whsec_…>' \
     --configuration 'processor.CTP_CLIENT_SECRET=<value>' \
     --configuration 'processor.STRIPE_SECRET_KEY=<value>'
   
   After a redeploy the deployment goes back through Deploying — same wait as the initial deploy. URLs remain stable.
   To pick up a newly published connector version, add --updateConnector:

   commercetools connect deployment redeploy \
     --key <your-deployment-key> \
     --updateConnector \
     --configuration 'processor.KEY=value'
   
   Without --updateConnector, redeploy keeps the current connector version and silently does not update the deployed code — it only refreshes config and restarts.
6. Optionally set processor.STRIPE_WEBHOOK_ID=<we_…> for the post-undeploy cleanup script

Checklist

• CLI authenticated with manage_connectors + manage_connectors_deployments
• Repo is public (or private via SSH URL with connect-mu granted read access)
• connectorstaged create used --repository-url ending in .git, included --creator-email
• Production-ready before publish (applies to private too): commercetools connect validate passes before staging; no debug/console.log logging, dev mocks, test scaffolding, commented-out code, or local-only config left in the repo; no hardcoded secrets/URLs; deps current; apps stateless
• engines.node pinned (e.g. 20.x) in every app's package.json (image-scan base image); dependency CVEs resolved by upgrading, not downgrading
• Every app has a passing test script; Vitest apps route through a wrapper that ignores the buildpack's injected Jest flags
• Repo contains only connector apps — no storefront/BFF/harness folder whose lockfile would be SCA-scanned
• Deployment draft lists all apps from connect.yaml, including the assets enabler (empty config) — else redeploy fails and no enabler URL is produced
• connectorstaged publish completed (status = published)
• deployment create passed all required config, secrets in secured config
• processor URL + enabler URL captured from deployment describe
• Stripe webhook registered at {processorUrl}/stripe/webhooks; signing secret stored in secured config

Deploy a public payment connector

Two clients — don't conflate them

This trips people up, and conflating them is the usual cause of auth/scope failures:

Step 1 — Authenticate the CLI

commercetools auth login --client-credentials \
  --client-id <CLI_CLIENT_ID> \
  --client-secret <CLI_CLIENT_SECRET> \
  --region <region e.g. europe-west1.gcp> \
  --project-key <projectKey>

Step 2 — Deploy the public connector directly

commercetools connect deployment create \
  --region <region> \
  --connector-key <public-connector-key>   # or --connector-id <id> \
  --type sandbox                            # preview | sandbox | production \
  --key <your-deployment-key> \
  --configuration '<applicationName>.<KEY>=<value>' \
  --configuration '<KEY>=<value>'

• Pass the config you derived in Step 2 of the skill via repeated --configuration flags ({applicationName}.{key}=value for app-specific, {key}=value for global). Secrets go here too — they land in the connector's secured config, not in the browser.
• During this step the platform surfaces the runtime scopes the connector will be granted (the auto-generated client) — review them; that's expected, not an error.
• Find the connector's key/id in the Connect marketplace (Merchant Center → Connect) or via the Connect API.

Step 3 — Get the URLs back

If something fails

• Auth/scope error on deploy → the CLI client is missing manage_connectors:{projectKey} / manage_connectors_deployments:{projectKey} (or you used a non-existent scope like manage_deployments). Fix the client's scopes and re-login.
• "connector not found" → wrong --connector-key/--connector-id, or the connector isn't available to your organization yet (install it from the marketplace first).
• Region mismatch → --region on both auth login and deployment create must equal the project's region.
• Anything about building, bundling, staging, or certifying a connector → that's commercetools-connect, not this path.

Checklist

• CLI authenticated with a client that has manage_connectors:{projectKey} + manage_connectors_deployments:{projectKey} (plus manage_api_clients:{projectKey} if credentials are auto-generated), or manage_project:{projectKey}
• Deployed via deployment create --connector-key … (no connectorstaged for a public connector)
• Config passed via --configuration; secrets in secured config, never the browser
• Runtime scopes reviewed at deploy time (auto-generated client — expected)
• processor URL + enabler URL captured for the integration steps

The full-flow integration test

Prerequisites

What it is (and isn't)

• It runs against a real deployed connector (processor + enabler URLs from config) and a real commercetools project, using the PSP's test cards — never live cards, never production keys.
• It reuses the test-harness.md flow as its driver for the browser half (session → enabler → submit), and verification.md as its oracle for the backend half (find the Payment, read its transactions).
• It is not a unit test and should not run on every commit. It needs secrets and a live deployment, it's slower, and a PSP sandbox hiccup can make it flake. Run it in a dedicated job (nightly, pre-release, or post-deploy smoke), gated on the connector config being present — skip with a loud, explicit message when config is absent so a missing secret reads as "not configured here," never as a silent pass. A silent pass on a missing secret is the same as having no test.
• Keep it to one or a few scenarios. Its value is breadth (it touches everything), not depth (the unit tests own the edge cases).

The flow it asserts

1. Mint session server-side (BFF)      -> assert: sessionId returned; response carries no secrets
2. Drive enabler + submit a test card  -> assert: onComplete fired / no enabler error
3. Find the Payment (verification.md)   -> assert: cart.paymentInfo has a Payment; transaction is Success;
                                                   paymentInterface matches the connector; exactly one Payment
4. Place the Order                      -> assert: Order created; cartState -> Ordered; idempotent on orderNumber
5. Capture (if manual) via processor    -> assert: a Charge/Success transaction appears on the Payment
6. Refund via the processor route       -> assert: a Refund transaction appears; Payment Intents API never called
7. Webhook reconciliation (async PSP)   -> assert: transaction reaches Success after the webhook (poll, don't sleep)

Steps 5–7 are conditional on the requirements from Step 1: skip capture if the flow is immediate-charge, skip the webhook wait for a fully-synchronous method. Assert only what the configured flow actually does — a test that asserts a manual capture against an automatic-capture deployment is testing the wrong contract.

Shape

import { describe, it, expect, beforeAll } from 'vitest';
import { loadConnectorConfig } from './support/config';
import { runHarnessFlow } from './support/harness';        // the test-harness.md flow, scripted
import { findPaymentForCart, findPaymentsForCart, getPayment, getCart } from './support/ct';
import { placeOrder, capture, refund } from '../src/backend';

const cfg = loadConnectorConfig();           // PROCESSOR_URL, ENABLER_URL, CT creds, project, region
const itLive = cfg ? it : it.skip;           // skip (loudly) when no deployment is configured

// poll until a predicate holds, so async webhook settlement doesn't force a brittle sleep
async function until<T>(fn: () => Promise<T>, ok: (v: T) => boolean, { tries = 20, gapMs = 1500 } = {}) {
  for (let i = 0; i < tries; i++) {
    const v = await fn();
    if (ok(v)) return v;
    await new Promise(r => setTimeout(r, gapMs));
  }
  throw new Error('condition not met within timeout — suspect the webhook (see backend-integration.md)');
}

describe('connector full flow (live deployment, test card)', () => {
  itLive('session -> pay -> Order -> capture -> refund leaves the right CT trace', async () => {
    // 1-2. server-side session + drive the enabler to submit a test card
    const { sessionId, cartId, result } = await runHarnessFlow(cfg, { testCard: '4242424242424242' });
    expect(result.error).toBeUndefined();

    // 3. the processor wrote the Payment — find it via the cart (verification.md)
    const payment = await until(
      () => findPaymentForCart(cfg, cartId),
      p => !!p && p.transactions.some(t => t.state === 'Success'),
    );
    expect(payment.paymentMethodInfo.paymentInterface).toBe(cfg.paymentInterface);  // e.g. 'checkout-stripe'
    const payments = await findPaymentsForCart(cfg, cartId);
    expect(payments).toHaveLength(1);                          // no duplicate Payment (frontend didn't create one)

    // 4. place the Order — and prove idempotency by doing it twice with the same orderNumber
    const orderNumber = `it-${sessionId}`;                     // deterministic per run; reused on retry
    const order  = await placeOrder({ cartId, orderNumber });
    const again  = await placeOrder({ cartId, orderNumber });
    expect(again.id).toBe(order.id);                           // converges on one Order
    expect(order.orderState).toBeDefined();
    const cart = await getCart(cfg, cartId);
    expect(cart.cartState).toBe('Ordered');

    // 5-6. capture then refund via the processor's operation routes
    if (cfg.captureMode === 'manual') {
      await capture({ paymentId: payment.id });
      const captured = await until(() => getPayment(cfg, payment.id),
        p => p.transactions.some(t => t.type === 'Charge' && t.state === 'Success'));
      expect(captured).toBeTruthy();
    }
    await refund({ paymentId: payment.id, amount: { centAmount: 100 } });
    const refunded = await until(() => getPayment(cfg, payment.id),
      p => p.transactions.some(t => t.type === 'Refund'));
    expect(refunded).toBeTruthy();
  }, 90_000);   // generous timeout: cold starts + webhook settlement
});

Reading a failure

Checklist

Gate: only write this test after the unit suite from backend-tdd.md exits 0.

• Unit suite green before this test was written — not after
• One end-to-end test drives a real deployed connector with a PSP test card (never live keys)
• It asserts the CT trace at each commit point (session, Payment+Success, Order, capture, refund), so a failure localizes the broken seam
• Reuses the test-harness.md flow as the driver and verification.md as the oracle
• Async settlement handled by polling with a timeout (until() helper), not a fixed sleep
• Asserts no duplicate Payment and that capture/refund went through the processor routes (not the Payment Intents API)
• Skips loudly (explicit it.skip or console.warn with a clear message) when deployment/secrets are absent — a silent pass on a missing secret is a broken test
• Runs in a dedicated job (nightly/pre-release/post-deploy), not on every commit

Payment connector — direct integration (backend-focused)

• processor (a service) — talks to the PSP, orchestrates payment operations, and owns the commercetools Payment object (creates it, adds transactions). Its behavior is driven by its connect.yaml config. You authenticate to it with a Checkout Session.
• enabler (an assets bundle) — a browser JS library on top of the PSP's UI components. It renders the payment UI and calls the processor. This is the frontend touchpoint — necessary, but a thin slice of the work.

"Checkout" is overloaded. Lowercase = the buying journey (always present). Uppercase Checkout = the commercetools product that runs that journey for you. On this path there is a checkout, but no Checkout product — which is exactly why the Payment is owned by the processor and refunds use the processor's routes, not the Payment Intents API. See backend-integration.md.

Workflow

Step 0 — Gather context (required, run first)

node scripts/docs-search.mjs \
  --query "<payment terms from the user's request, e.g. 'payment connector processor session capture refund webhook'>" \
  --app-name "<current-app ex: claude, copilot, codex>" \
  --model "<current-model>" \
  --skill-name "commercetools-connect" \
  --limit 10

Step 1 — Extract requirements (do this before any config or code)

1. Which PSP / connector, and is it deployed? Get the connector and version and, if deployed, its processor URL and enabler URL (Merchant Center deployment view, or the Connect deployments API).
2. Region and project? e.g. europe-west1.gcp, project my-project — the Sessions API host and the CTP_*_URL config are region-specific.
3. Capture mode? Charge immediately, or authorize now and capture later (on fulfillment)? → drives the capture-method config and when you create the Order.
4. Saved payment methods / returning customers? Should cards be saved for reuse? → drives the save-cards config and requires a customerId on the cart.
5. Refunds / partial captures? Will the business do partial refunds or split captures? → drives the multi-operations config.
6. Which payment methods, and drop-in vs. web components? Drop-in (one element) is the default; web components give per-method layout control.
7. Storefront origin(s) and post-payment return URL? → drives CORS and the return-URL config (a frequent silent breaker).
8. Sync or async settlement? Some methods/PSPs finalize via webhook → drives whether Order creation waits on the webhook.
9. Anything special or non-standard? (always ask — open-ended) The eight questions above cover the common shape, but they don't cover everything, and the requirements that decide config-vs-fork-vs-custom are often the ones a fixed list never asks. So explicitly ask the user: "Beyond the above, are there any specific constraints or behaviors you need?" Prompt with examples to jog memory — compliance/regulatory (PCI scope, SCA/3DS exemptions, local mandates), B2B (purchase-order numbers, invoices, multi-buyer approval), subscriptions/recurring or installments, multi-currency or per-market pricing, marketplace split payments/payouts, existing PSP contract terms or a specific PSP account/merchant id, custom fraud or risk-scoring, surcharging, stored-credential mandates, or anything that must appear on the PSP side (metadata, descriptors). Capture each as its own requirement line; don't force it into one of the eight slots.

Step 1.5 — Is a certified connector enough? (decide before wiring or building)

1. Public connector covers everything → install + configure (Step 2). Don't build. Installing it (CLI auth, scopes, deployment create) is covered in deploy-public-connector.md — note it is not the connectorstaged flow.
2. Supported PSP, gap looks like a capability → prove it isn't config first. Most "missing" behaviors (partial refunds, manual capture, saved cards) are connect.yaml toggles → back to rung 1. See config-from-requirements.md.
3. Supported PSP, genuine gap config can't close → fork/extend the public connector (its repo is open source); add only the delta and deploy as an Organization connector. Don't rebuild — you'd throw away a working, maintained connector. Hand off to commercetools-connect. For monitoring the connector you build: deployment logs, structured logging, and the poison-message runbook are in observability-operations.md.
4. No public connector for the PSP at all → build from the payment integration template. This can be done inline (within this skill session) when the user explicitly asks to build custom — see the stripe.md "Building a custom Stripe connector" section for the key gotchas (raw body, API version, POST vs GET route). For staging, publishing, and deploying the built connector see deploy-custom-connector.md. Hand off to commercetools-connect when the full Connect publish/certification lifecycle is the goal. For monitoring: observability-operations.md.

Step 2 — Derive the provider config from the requirements

Produce, for the user:

• a filled standardConfiguration block (region URLs, capture method, saved-cards, multi-ops, billing collection, return URL, allowed origins, payment-interface name, …),
• the securedConfiguration keys they must supply (PSP secret key, webhook signing secret, CT client id/secret) — names only, never invent values,
• the API-client scopes the connector needs,
• a short rationale per non-obvious key tied back to their requirement.

Step 3 — Frontend touchpoint (reference)

Step 4 — Build the backend (the main body of work), test-first

1. Write a failing test that names the behavior and asserts the outcome.
2. Run it. Confirm it fails for the right reason — not a missing import, not a wrong mock, but because the behavior is absent. A test that passes before you've written the code is testing nothing and must be fixed before proceeding.
3. Write the least code that makes it pass. No extra logic, no generalizing ahead of the next test.
4. Refactor with the test as a safety net. Then repeat for the next behavior.

• Every behavior listed in the backend-tdd.md checklist has a passing test.
• The test suite runs clean with npm test and no secrets in the environment.

1. Server-side session creation (BFF) — mint token/cart/session on the server so secrets and manage_sessions never reach the browser; verify cart ownership (IDOR) and create the session as late as possible. The browser gets only sessionId + processor/enabler URLs.
2. Order creation — convert the cart to an Order after authorization completes (and, for async settlement, after the webhook confirms Success), with a unique pre-generated orderNumber for idempotency. Timing follows the capture mode chosen in Step 1.
3. Post-purchase operations — capture / refund / cancel on the authorized Payment via the processor's own operation routes, not the Checkout Payment Intents API (which only works for payments the Checkout product created). Whether partial captures/refunds are even available depends on the multi-ops config from Step 2.
4. Webhook reconciliation — treat the commercetools Payment (driven by the PSP webhook the processor verifies) as the authoritative state, not the browser's onComplete. A transaction stuck Pending almost always means the webhook.

Step 5 — Verify the round trip, then lock it in with a full-flow integration test

References

Checklist

Requirements

• PSP/connector + version; processor URL and enabler URL (or routed to deploy)
• Region + project; capture mode; saved-cards? partial refunds/captures? methods; origins + return URL; sync/async settlement
• Asked the open-ended "anything special/non-standard?" question; captured each special requirement as its own line
• Requirements block written and confirmed with the user; special requirements flagged into the Step 1.5 fit-check

Connector fit (decide before wiring/building)

• Checked live marketplace + supported-PSPs docs (not memory); named the connector + version
• PSP, methods, integration type, capabilities, region compared to the requirements; apparent gaps re-checked as config
• Ladder rung chosen: configure (1) · config-closes-gap (2) · fork/extend public connector (3) · build from template (4)
• For a real gap on a PSP that has a public connector, chose fork/extend over rebuild

Config (the deliverable)

• Only documented connect.yaml envelope fields used (no invented keys); file placed at the repository root, not a nested folder
• standardConfiguration filled from the requirements, with a rationale per non-obvious key
• securedConfiguration keys listed (values supplied by the user, never invented)
• API-client scopes cover managing payments + reading sessions
• MERCHANT_RETURN_URL absolute w/ scheme; ALLOWED_ORIGINS includes the storefront origin
• Capture-method / saved-cards / multi-ops config match the chosen flow

Backend

• Token/cart/session creation server-side; browser gets only sessionId + processor/enabler URLs
• Order created from cart after authorization (and webhook Success for async), idempotent via orderNumber
• Capture/refund/cancel routed through the processor's operation routes (not the Payment Intents API)
• Webhook reconciliation in place; Pending transactions traced to webhook delivery

• Vitest (or equivalent) installed and npm test runs before any implementation code is written
• Each backend behavior written test-first: failing test confirmed red for the right reason → least code to pass → refactor
• No implementation function was written before its test — if you find yourself writing code without a red test, stop and write the test first
• Boundary mocked (PSP/processor/Sessions API behind a port); orchestration logic not mocked; unit suite runs with no deployment/secrets
• Happy path pinned per piece (session minted, Order created once marked Ordered, capture/refund recorded) — the one a broad refactor silently breaks
• Invariants pinned as tests: IDOR rejection, no-secret-leak, Order idempotent on orderNumber, gate-on-Success (both Pending and Failure blocked), capture/refund via processor (Payment Intents API untouched), webhook idempotent on redelivery
• npm test runs clean with zero secrets in the environment

Verification

• Test-card payment completed; commercetools Payment found with a Success transaction
• (Production) Order created; a refund through the processor succeeds
• Full-flow integration test drives the real deployed connector with a test card, asserts the CT trace at each commit point, polls (not sleeps) for async settlement, and skips loudly when unconfigured

Stripe payment connector

The connector

• Connector: Stripe Payment for Checkout (stripe-payment-connector).
• Source: stripe/stripe-commercetools-checkout-app — a monorepo with processor/ (service) and enabler/ (assets).
• Verify the version you're integrating before trusting any specific key — Stripe iterates the connector. Config keys are read from a recent release; re-check the deployment's connect.yaml if behavior differs.

Enabler bundle (browser)

• File: connector-enabler.umd.js (and connector-enabler.es.js). Load the UMD one via <script> — see contract pitfall 5.
• UMD global: window.Connector → window.Connector.Enabler.
• Internally imports @stripe/stripe-js, which is exactly why dynamic ES import() is fragile here.

<script src="https://assets-….{region}.commercetools.app/connector-enabler.umd.js"></script>
<script>
  const { Enabler } = window.Connector;
  const enabler = new Enabler({ processorUrl, sessionId, locale: 'en-US', onComplete, onError });
  const dropin = await (await enabler.createDropinBuilder('embedded')).build({ showPayButton: false });
  dropin.mount('#dropin-container');   // then wait for `ready` before enabling Pay (pitfall 7)
</script>

Configuration keys (connect.yaml)

Secured (secrets):

Session metadata for Stripe

{ "metadata": { "processorUrl": "https://service-….europe-west1.gcp.3.sandbox.commercetools.app" } }

API client scopes

Notes:

• Checkout splits session scopes: manage_sessions:{projectKey} grants creating a session (the Storefront BFF needs this), while view_sessions:{projectKey} grants reading one — the latter is the scope required for connectors to interact with Checkout and validate sessions, so the Processor needs view_sessions. See Checkout Scopes.
• manage_orders covers reading carts (needed for cart version lookups and addPayment) — do not request view_orders or manage_my_orders unless the client was explicitly granted them.
• The processor and storefront BFF can share a single API client in development, but should use separate clients in production to enforce least-privilege.

Webhook setup

Test cards

Any future expiry, any CVC, any postal code.

Building a custom Stripe connector (from the payment-integration template)

When building your own connector (ladder rung 4 — no public connector, or forking), two things differ from the public connector experience:

npm install fastify-raw-body

import rawBody from 'fastify-raw-body';

await server.register(rawBody, {
  field: 'rawBody',
  global: false,      // opt-in per route, not global
  encoding: false,    // keep as Buffer, not string
  runFirst: true,
  routes: ['/stripe/webhooks'],
});

fastify-raw-body v5 replaces the JSON content-type parser globally. Despite global: false, v5 replaces Fastify's default JSON content-type parser for ALL routes (not just webhook routes). The global flag only controls the preParsing hook, not the parser replacement. This means any POST route that receives Content-Type: application/json with an empty body ("") will be rejected by the patched almostDefaultJsonParser — even POST /payments. The fix: always send body: "{}" (a valid empty JSON object) from the enabler's fetch call to POST /payments, never an empty string or no body at all.

stripe.elements({
  mode: 'payment',
  amount: cartElement.cartInfo.amount,          // centAmount from the CT cart
  currency: cartElement.cartInfo.currency.toLowerCase(),
  capture_method: cartElement.captureMethod,    // 'automatic' | 'manual'
});

// GET /config-element/:paymentComponent — session-authenticated
async initializeCartPayment() {
  const ctCart = await this.ctCartService.getCart({ id: getCartIdFromContext() });
  const amount = await this.ctCartService.getPaymentAmount({ cart: ctCart });
  return {
    cartInfo: { amount: amount.centAmount, currency: amount.currencyCode },
    captureMethod: getConfig().stripeCaptureMethod,
    collectBillingAddress: getConfig().stripeCollectBillingAddress,
    layout: JSON.stringify({ type: 'tabs', defaultCollapsed: false }),
  };
}

await stripe.paymentIntents.create({
  amount: amountPlanned.centAmount,
  currency: amountPlanned.currencyCode.toLowerCase(),
  capture_method: cfg.stripeCaptureMethod,
  automatic_payment_methods: { enabled: true }, // not payment_method_types: ['card']
  metadata: { ... },
});

// 1. Validate the form
const { error: submitError } = await elements.submit();
if (submitError) { /* handle */ return; }

// 2. Create the PaymentIntent server-side NOW (not at mount time)
const res = await fetch(`${processorUrl}/payments`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Session-Id': sessionId },
  body: '{}',
});
const { clientSecret } = await res.json();

// 3. Confirm with the clientSecret
const { error, paymentIntent } = await stripe.confirmPayment({
  clientSecret,   // ← required for deferred-intent
  elements,
  confirmParams: { return_url: merchantReturnUrl },
  redirect: 'if_required',
});

const pi = await stripe.paymentIntents.retrieve(paymentIntentId);
const stripeChargeId = pi.latest_charge as string; // ch_xxx