All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading