Getting Started with Stripe Payment for Medusa

In this guide, you'll learn how to install and configure the Stripe payment provider for Medusa, set up its webhook and the domains for wallets, and switch from Medusa's built-in Stripe provider.

• Medusa v2.17.2 or later
• Node.js v22.23.4, v24.22.1, v26.12.1 or later
• A Stripe account – sign in or create one. Stripe works with businesses in supported countries only
• Integration Module

yarn add @gorgo/medusa-integration @gorgo/medusa-payment-stripe

Add the configurations of the Integration Module provider and of the Medusa Payment Module in your medusa-config.ts file of the Medusa Admin application:

medusa-config.ts
1// ...
2const STRIPE_INTEGRATION_ID = "stripe-1"
3
4module.exports = defineConfig({
5  // ...
6  plugins: [
7    // ...
8    {
9      resolve: "@gorgo/medusa-integration",
10      options: {
11        encryptionKey: process.env.INTEGRATION_ENCRYPTION_KEY,
12        providers: [
13          {
14            resolve: "@gorgo/medusa-payment-stripe/providers/integration-stripe",
15            id: STRIPE_INTEGRATION_ID,
16            options: {},
17          },
18        ],
19      },
20    },
21    {
22      resolve: "@gorgo/medusa-payment-stripe",
23      options: {},
24    },
25  ],
26  modules: [
27    // ...
28    {
29      resolve: "@medusajs/medusa/payment",
30      options: {
31        providers: [
32          {
33            resolve: "@gorgo/medusa-payment-stripe/providers/payment-stripe",
34            id: "stripe",
35            options: {
36              id: STRIPE_INTEGRATION_ID
37            }
38          },
39        ],
40      },
41    },
42  ],
43})

The payment provider registered this way gets the id pp_stripe_stripe, and its webhook route is /hooks/payment/stripe_stripe.

Add environment variables with your secret Encryption Key:

.env
INTEGRATION_ENCRYPTION_KEY=supersecret

The secret key, the publishable key and the other Stripe settings are not provider options. You enter them in Medusa Admin, as described in Manage Stripe Settings in Medusa Admin.

To properly handle payment notifications from Stripe, add a webhook endpoint for your store in the Stripe Dashboard:

1. Open Webhooks in the Stripe Dashboard, in the test or live mode that matches your keys.

2. Add an endpoint with the URL in the following format:

   Webhook URL
   https://{YOUR_MEDUSA_DOMAIN}/hooks/payment/stripe_stripe

   Change {YOUR_MEDUSA_DOMAIN} with your medusa store domain.

3. Select the payment_intent.succeeded and payment_intent.amount_capturable_updated events, and save the endpoint.

4. Reveal the endpoint's signing secret, which starts with whsec_, and enter it in the Webhook signing secret field of the Stripe settings in Medusa Admin. Test connection then checks that an enabled endpoint whose URL contains /hooks/payment/stripe_ exists in that mode and sends both events.

During development, the Stripe CLI forwards the events to your local backend and prints the signing secret to use:

stripe listen --forward-to localhost:9000/hooks/payment/stripe_stripe

Apple Pay, Google Pay and Link appear only on domains registered with Stripe. Register every domain and subdomain that shows the checkout, as described in Stripe's guide to registering payment method domains. A domain registered in live mode is registered in test mode too.

Until the domain is registered, the wallets stay hidden, and the express checkout row shows no Stripe button.

The plugin registers under the same provider id and webhook URL as Medusa's built-in @medusajs/payment-stripe, so it replaces it without a data migration. The payments, the sessions and the saved cards the built-in provider created stay in the database, and the plugin captures, refunds and cancels those payments.

To switch:

1. Replace @medusajs/medusa/payment-stripe in the providers of the Payment Module with @gorgo/medusa-payment-stripe/providers/payment-stripe, keeping id: "stripe", and register the integration provider as shown in Configuration. Keep only one of the two providers with id: "stripe".

2. Enter the keys in Medusa Admin. The built-in provider read apiKey and webhookSecret from medusa-config.ts, and the plugin reads them from its settings.

3. Set Payment capture in the settings. The built-in provider only authorizes by default, and its capture: true option matches Capture right away.

4. Keep the webhook endpoint you already have in the Stripe Dashboard, since the URL stays /hooks/payment/stripe_stripe, and enter its signing secret in the settings.

The built-in provider also registered a provider per payment method, such as stripe-ideal or stripe-bancontact. The plugin has one provider, and the Payment Element shows the methods your Stripe account or the payment method configuration enables, iDEAL and Bancontact included. Stripe does not offer BLIK on a PaymentIntent created at payment time, as its guide to collecting payment details before creating an Intent notes, so BLIK is not available.