# Add Stripe Checkout to a Medusa Store

Yes. An agent enables Medusa's bundled Stripe provider in medusa-config.ts, adds it to your regions, documents the webhook, tests the provider list and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-stripe-checkout/medusa/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads both halves of the store before it changes either, because in a Medusa monorepo the storefront is often ahead of the backend. In a repository laid out like medusajs/dtc-starter, `apps/backend/medusa-config.ts` sets only `projectConfig`: the database URL, the three CORS lists, `jwtSecret` and `cookieSecret`, with no `modules` array at all, so no payment provider beyond the built-in `pp_system_default` is registered. `apps/backend/package.json` pins every `@medusajs/*` package at 2.22.1, and `src/migration-scripts/initial-data-seed.ts` creates one region, `Europe` in `eur`, with `payment_providers: ["pp_system_default"]`. The storefront, by contrast, is ready: `apps/storefront/package.json` has `@stripe/stripe-js` and `@stripe/react-stripe-js`, `src/lib/constants.tsx` maps `pp_stripe_stripe`, `pp_stripe-ideal_stripe` and `pp_stripe-bancontact_stripe` to titles and icons and defines `isStripeLike`, `checkout/components/payment-wrapper` loads Stripe from `NEXT_PUBLIC_STRIPE_KEY`, and `src/app/api/payment-return/route.ts` already handles the redirect back from an off-site authorization. The `.env.template` leaves `NEXT_PUBLIC_STRIPE_KEY` empty.

The provider ships inside `@medusajs/medusa`, so there is nothing to install. The agent adds a `modules` entry to `medusa-config.ts` that resolves `@medusajs/medusa/payment` with one provider, `@medusajs/medusa/payment-stripe`, `id: "stripe"`, and options `apiKey: process.env.STRIPE_API_KEY` and `webhookSecret: process.env.STRIPE_WEBHOOK_SECRET`, leaving `capture` at its default of false so authorized payments are captured when the order is placed, which is how the storefront's `placeOrder` call expects it. It adds the two variables to `apps/backend/.env.template` with a comment on where each comes from and reads them through `loadEnv`, which the config already calls. With `id: "stripe"` the provider's identifier is `pp_stripe_stripe`, the exact key the storefront's `paymentInfoMap` already lists, so no storefront code changes.

A provider registered in config is not yet offered at checkout: it must be enabled on a region. Rather than make that a manual admin step, the agent writes `src/scripts/enable-stripe.ts`, run with `medusa exec`, that uses `updateRegionsWorkflow` from `@medusajs/medusa/core-flows`, the same workflow the kit's `region-store-policies.ts` migration script uses, to add `pp_stripe_stripe` to every region's `payment_providers` while keeping `pp_system_default`, and documents the equivalent admin path, Settings → Regions → edit region, for a store that prefers clicking. It also records the webhook: Stripe must POST to `<backend url>/hooks/payment/stripe_stripe` with `payment_intent.succeeded`, `payment_intent.amount_capturable_updated`, `payment_intent.payment_failed` and `payment_intent.partially_funded`, and the signing secret of that endpoint is `STRIPE_WEBHOOK_SECRET`. The CORS lists in `.env.template` are left alone, since the Stripe calls go browser-to-Stripe and backend-to-Stripe, never through them.

In its sandbox the agent installs with `pnpm install --frozen-lockfile`, as `packageManager` says `pnpm@10.11.1`, starts a Postgres, runs `medusa db:migrate` so the seed migration script creates the Europe region, runs the new script and queries the region to show `pp_stripe_stripe` listed, then boots the backend with a Stripe test key and asserts that `GET /store/payment-providers?region_id=…` returns both providers. It writes `integration-tests/http/payment-providers.spec.ts` with `@medusajs/test-utils`'s `medusaIntegrationTestRunner` for the same check, so `pnpm test:integration:http` covers it from now on. The storefront gets `NEXT_PUBLIC_STRIPE_KEY` filled in from the sandbox's test publishable key only for a `next build`, never committed.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Enable Stripe card payments in this Medusa store. Read apps/backend/medusa-config.ts, apps/backend/package.json, apps/backend/.env.template, apps/backend/src/migration-scripts/initial-data-seed.ts and region-store-policies.ts, apps/backend/integration-tests, apps/storefront/.env.template, apps/storefront/src/lib/constants.tsx and the checkout components under apps/storefront/src/modules/checkout first. Register the bundled Stripe provider under the payment module in medusa-config.ts with id stripe, reading STRIPE_API_KEY and STRIPE_WEBHOOK_SECRET from the environment, and add both to the backend .env.template with comments. Write a medusa exec script that adds pp_stripe_stripe to every region's payment providers with updateRegionsWorkflow while keeping the manual provider, and an integration test that lists the store payment providers for the seeded region and expects both. Document the Stripe webhook URL, the four events to subscribe to and the admin path for enabling the provider in the pull request. Run pnpm install --frozen-lockfile, migrate a fresh database, run the script and the test with a Stripe test key, and build the storefront once. Do not change the storefront source, the CORS settings or any package version.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `apps/backend/medusa-config.ts` and `apps/backend/.env.template`, and adds `apps/backend/src/scripts/enable-stripe.ts` and `apps/backend/integration-tests/http/payment-providers.spec.ts`. Its description holds the region query showing `pp_stripe_stripe` beside `pp_system_default`, the test output, the webhook URL with the four Stripe events, and the two settings only a person with the Stripe dashboard can complete: the endpoint and its signing secret, and the keys in each environment.

Before merging, a reviewer decides whether `capture` should stay false or move to true for a store that wants funds taken at authorization, whether iDEAL and Bancontact, which the storefront already knows how to display, should be registered as further providers under the same `id`, and whether the enable script should be re-run in production or the region edited in the admin.

## Run it on every new Medusa project

A team that stands up a store per brand or per market from the same starter runs this once per new repository from its own server: one `POST /o/{org}/sessions` per repository, each with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than a second pull request. Each run reads its own `medusa-config.ts`: a backend that already has a `modules` array gets the provider appended to it, and one whose seed creates several regions gets every region updated.

After the first run, the one worth repeating is the check that a Medusa release keeps the provider working. An automation on the Project with a `schedule` trigger (`every` `1d` in your `timezone`) and the prompt "for each open pull request that Update Medusa opened, migrate a fresh database on its branch, run the enable script and the payment-providers integration test, and comment on it with the result" checks each release the day it arrives; a pull request the Actions bot opened fires no `github` trigger, which is why the check runs on a schedule.

## Why run it on Rush?

Enabling a payment provider spans a config file, an environment template, a region record in the database and a webhook in a third-party dashboard, and the checkout only works when all four agree on one string, `pp_stripe_stripe`. The agent reads the storefront's provider map first, so the backend is configured to match the UI that already exists rather than the other way round, and proves the region change with a query instead of a sentence.

The migration, the script run, the provider listing and the test stay with the run and are in the pull request. A reviewer sees the provider offered for the seeded region before any real key is set, and the same request runs across every store a team operates at once.

## Frequently asked questions

### Does the storefront need code changes?

Not for card payments. `src/lib/constants.tsx` already maps `pp_stripe_stripe` to a credit card entry, `isStripeLike` matches it, `payment-wrapper` loads Stripe from `NEXT_PUBLIC_STRIPE_KEY`, and `app/api/payment-return/route.ts` handles the return from a bank redirect. Filling that one variable in `.env.local` is the storefront's whole share of the work.

### Why is the webhook secret marked as a deployment step?

Because Stripe signs each webhook with a secret that exists only once the endpoint is created in the Stripe dashboard for a public URL, and a sandbox has none. The config reads `STRIPE_WEBHOOK_SECRET` so the value drops in per environment; the URL to register is `<backend url>/hooks/payment/stripe_stripe`.

### Why a script instead of enabling the provider in the admin?

The script makes the change repeatable: a fresh database after `medusa db:migrate` has the Europe region with only the manual provider, and `medusa exec src/scripts/enable-stripe.ts` brings it to the same state every time, which is also what the integration test relies on. The admin path does the same thing by hand and the pull request names it.

### Will the manual payment option disappear?

No. The script appends `pp_stripe_stripe` to each region's `payment_providers` and keeps `pp_system_default`, so test orders and the existing flow keep working. Removing the manual provider is a one-line change in the script once the Stripe keys are live.

### Does it work with the Medusa update workflow?

Yes. `.github/workflows/update.yaml` bumps every `@medusajs/*` package together, and the provider is part of `@medusajs/medusa`, so it moves with them; the new integration test is what tells you if a release changed its behavior.

## More Medusa jobs

- [Write Integration Tests for a Medusa Backend](https://getrush.ai/run/write-integration-tests/medusa/)
- [Write Unit Tests for a Medusa Backend](https://getrush.ai/run/write-unit-tests/medusa/)
- [Add Dependabot to a Medusa Monorepo](https://getrush.ai/run/add-dependabot/medusa/)

## The same job on other stacks

- [Add Stripe Checkout to a Rails App](https://getrush.ai/run/add-stripe-checkout/rails/)
- [Add Stripe Checkout to a Django App](https://getrush.ai/run/add-stripe-checkout/django/)
- [Add Stripe Checkout to an Express App](https://getrush.ai/run/add-stripe-checkout/express/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
