---
updatedAt: 2026-10-14T22:19:55.000Z
agentTools:
  projectIndex: https://docs.constructor.com/llms.txt
---

# Stripe

The Constructor + Stripe integration lets shoppers move from product discovery to checkout within an agentic experience, such as the AI Shopping Agent (ASA) or Product Insights Agent (PIA).

Constructor’s <Anchor target="_blank" href="https://constructor-io.github.io/constructorio-ui-checkout">Checkout UI library</Anchor> provides everything you need to integrate Stripe's Embedded Checkout form within the above agentic experiences. This article covers the backend setup and Stripe Checkout Session configuration patterns commonly required with this integration.

# Scope and responsibilities

Constructor provides:

* Client-side Checkout UI library components and APIs used to render and orchestrate the checkout experience

You are responsible for:

* Creating and managing the shopper’s cart and pricing logic
* Creating and (optionally) updating Stripe Checkout Sessions
* Tax configuration, tax registrations, and product tax code mapping (when applicable)
* Shipping carrier logic and rate calculation (when applicable)

# Payment security and data handling

Stripe hosts the embedded checkout UI and handles payment details.

* Constructor does **not** receive or store shopper payment card details.
* Your backend creates Stripe Checkout Sessions using your Stripe secret key.
* The UI library only receives the Stripe `clientSecret` plus your Stripe publishable key.

# Requirements

## Stripe

* Stripe account with **Embedded Checkout** enabled
* Stripe **server** SDK **v18+**
* Stripe must enable `ui_mode: 'form'` (embedded form) on your account if you plan to use form mode

## Library

Minimum supported versions noted below:

* Node.js **>= 18**
* React **>= 16.12.0**
* React DOM **>= 16.12.0**
* `@stripe/stripe-js` **>= 9.3.1**
* `@stripe/react-stripe-js` **>= 6.6.0**
* `@constructor-io/constructorio-ui-components` **>= 1.4.0**

## Your application

You will need:

* A server endpoint that creates Stripe Checkout Sessions and returns `{ clientSecret, publishableKey }`
* A place in your agent experience to mount a multi-step checkout experience (modal, routed pages, or single-page)
* Access to current cart contents and currency in your app (used to build `line_items`)

Recommended:

* A stable cart identifier (to help prevent duplicate checkout sessions when requests are retried)

# Agent and checkout UI libraries

Constructor's agent UI libraries provide the “agent surface” where the shopper interaction happens, whereas the Checkout UI library provides the checkout flow primitives that you mount inside that surface.

## Related agent UI libraries&#x20;

Agentic checkout is typically embedded into one of Constructor’s agent UI libraries:

* **AI Shopping Assistant (ASA) UI library**
  * GitHub: <Anchor target="_blank" href="https://github.com/Constructor-io/constructorio-ui-asa">Constructor-io/constructorio-ui-asa</Anchor>
  * npm: <Anchor target="_blank" href="https://www.npmjs.com/package/@constructor-io/constructorio-ui-asa">@constructor-io/constructorio-ui-asa</Anchor>
  * Storybook: <Anchor target="_blank" href="https://constructor-io.github.io/constructorio-ui-asa">constructor-io.github.io/constructorio-ui-asa</Anchor>
* **Product Insights Agent (PIA) UI library**
  * GitHub: <Anchor target="_blank" href="https://github.com/Constructor-io/constructorio-ui-pia">Constructor-io/constructorio-ui-pia</Anchor>
  * npm: <Anchor target="_blank" href="https://www.npmjs.com/package/@constructor-io/constructorio-ui-pia">@constructor-io/constructorio-ui-pia</Anchor>
  * Storybook: <Anchor target="_blank" href="https://constructor-io.github.io/constructorio-ui-pia">constructor-io.github.io/constructorio-ui-pia</Anchor>

The agent UI libraries provide the “agent surface” where the shopper interaction happens. The Checkout UI library provides the checkout flow primitives that you mount inside that surface.

## Checkout UI library

For detailed integration walkthroughs (React, non-React, standalone) and the full Checkout UI library API surface (steps, routing, persistence, session lifecycle), refer to the Checkout UI library Storybook:

* <Anchor target="_blank" href="https://constructor-io.github.io/constructorio-ui-checkout">Checkout UI library Storybook</Anchor>

Key pages:

* <Anchor target="_blank" href="https://constructor-io.github.io/constructorio-ui-checkout/?path=/docs/core-sessions--docs">Sessions</Anchor>
* <Anchor target="_blank" href="https://constructor-io.github.io/constructorio-ui-checkout/?path=/docs/core-steps--docs">Steps</Anchor>

# How checkout works

1. Your application starts a checkout flow inside the ASA or PIA UI.
2. The Checkout UI library calls your `onCreateSession` callback.
3. Your backend creates a Stripe Checkout Session (`ui_mode: 'form'`) and returns `{ clientSecret, publishableKey }`.
4. The UI library displays Stripe Embedded Checkout (form).
5. After payment, your application confirms/fulfils the order and displays confirmation.

# Prepare your backend for checkout

Before you integrate Stripe via the Checkout UI library, you’ll need the following from your Stripe account and backend:

## 1) Create a Stripe secret key

Your backend will need a Stripe **secret** API key. Stripe secret keys are typically either:

* **Restricted** secret keys (`rk_*`) — **recommended** for least-privilege integrations
* **Standard** secret keys (`sk_*`) — broader access; use only if your Stripe setup requires it

<Anchor target="_blank" href="https://docs.stripe.com/keys#create-a-secret-key">Create a dedicated key for this integration</Anchor> and store it in your secrets manager. Copy the key value immediately as you will not be able to retrieve it later.

**Recommended guidelines:**&#x20;

* Restricted keys typically start with `rk_`
* Give it a descriptive name, such as “Constructor Agent — Checkout”
* Limit permissions to the minimum required for your implementation. At a minimum, your backend must be able to **create Checkout Sessions**.

## 2) Locate your Stripe publishable key

You will also need your Stripe publishable key (`pk_test_*` or `pk_live_*`). Your backend returns this value to the UI library as `publishableKey`.

## 3) Implement the Checkout Session creation endpoint

Your backend must expose an endpoint (e.g., `POST /api/checkout-session`) that:

1. Receives the shopper’s current cart context from your application (directly or via server-side lookup).
2. Creates a Stripe Checkout Session using `ui_mode: 'form'`.
3. Returns JSON with:
   * `clientSecret` (from `session.client_secret`)
   * `publishableKey`

The Checkout UI library consumes this response in `onCreateSession`.

**Operational guidance:**

* Do not log secret keys or full client secrets.
* Use an idempotency key to prevent duplicate checkout sessions (see the Storybook <Anchor target="_blank" href="https://constructor-io.github.io/constructorio-ui-checkout/?path=/docs/core-sessions--docs">Sessions</Anchor> page).

## 4) Implement a session-update endpoint (optional)

If you support changes after session creation (e.g., shipping selection, address-based tax/shipping, cart edits, promotions), implement a backend endpoint that can update the active Stripe session and wire it to `onUpdateSession`.

Implementation details depend on your commerce, tax, shipping, and promotions stack.

This doc focuses on the **additional Stripe configuration patterns** (tax and shipping) that are commonly needed for a production-ready integration.

# Additional configuration options (tax and shipping)

This article does not assume a specific tax or shipping provider. When using the Checkout UI library, you enable Stripe tax and shipping behavior by adding parameters to your server-side `stripe.checkout.sessions.create(...)` call, and (when needed) updating the active session via `onUpdateSession`.

## Automatic tax calculation

If you use **Stripe Tax**, you can enable automatic tax calculation in the Checkout Session:

```jsx
const session = await stripe.checkout.sessions.create({
  // ... other params
  automatic_tax: { enabled: true },
  shipping_address_collection: {
    allowed_countries: merchantConfig.countries,
  },
})
```

**Notes:**

* You must enable <Anchor target="_blank" href="https://docs.stripe.com/tax/set-up">Stripe Tax</Anchor> in your Stripe account. If using an <Anchor target="_blank" href="https://docs.stripe.com/tax/third-party-apps">approved third-party Stripe tax app</Anchor>, you will need to install that app from the Stripe Marketplace before selecting it in your Stripe account.
* With third-party tax providers, requirements vary by provider and by how your catalog is mapped to tax codes.

## Shipping address collection and shipping options

To collect a shipping address in checkout, set `shipping_address_collection`.

If you want Stripe to display multiple shipping methods, you can set `shipping_options`. A common pattern is:

1. Create the session with an address collection requirement and a placeholder shipping option.
2. After the shopper enters an address, recalculate available shipping methods in your backend.
3. Update the session via your own endpoint and wire it through `onUpdateSession`.

Example placeholder shipping option:

```jsx
const session = await stripe.checkout.sessions.create({
  // ... other params
  shipping_address_collection: {
    allowed_countries: merchantConfig.countries,
  },
  shipping_options: [
    {
      shipping_rate_data: {
        type: 'fixed_amount',
        display_name: 'Shipping calculated at checkout',
        fixed_amount: { amount: 0, currency: merchantConfig.currency },
      },
    },
  ],
})
```

Important:

* Your team owns carrier logic and rate calculation. Constructor does not provide a shipping-rate service.
* If you implement an address-based rate service, limit the number of returned options (e.g., 3-5) for a better shopper experience.