Skip to main content


View plugin here


Handling payments is at the core of every commerce system; it allows us to run our businesses. Consequently, a vast landscape of payment providers has developed, each with varying cost models, implementational specifications, and analytical capabilities.

As a consequence, one might ask, which one(s) should I choose? Medusa makes exchanging enabled payment providers easy through its unified payment API. Here, one may select payment provider plugins already existing (PayPal, Klarna, and Stripe), or develop new ones.

Using the medusa-payment-stripe plugin, this guide will show you how to set up your Medusa project with Stripe as a payment provider.

Stripe is a battle-tested and unified platform for transaction handling. Stripe supplies you with the technical components needed to handle transactions safely and all the analytical features necessary to gain insight into your sales. These features are also available in a safe test environment which allows for a concern free development process.


This guide assumes that you have set up a medusa project (See this guide). Furthermore, this guide will be using the Gatsby starter as our storefront (See this guide) and the Admin panel to manage our store (See the github installation guide here).


The first step is to install the medusa-payment-stripe plugin in your Medusa project using your favorite package manager:

# yarnyarn add medusa-payment-stripe

# npmnpm install medusa-payment-stripe

Then in your medusa-config.js , add the plugin to your plugins array:

module.exports = { // ... other options   plugins: [       // ... other plugins       {            resolve: `medusa-payment-stripe`,            options: {                api_key: STRIPE_API_KEY,                webhook_secret: STRIPE_WEBHOOK_SECRET,            },       },   ];}

Now head over to Stripe and create your account. You can then click API Keys on your dashboard, and here you will see two keys. We suggest using the test environment during development, and therefore you should make sure that you are seeing the keys to the test environment (These keys start with pk_test_ and sk_test_ respectively).

Now open your .env file for the Medusa project and store your secret key in the STRIPE_API_KEY variable:

# .envSTRIPE_API_KEY=<your key here>

Note: For production you should also create a webhook on Stripe (also available on your dashboard) and store its secret in the STRIPE_WEBHOOK_SECRET variable. We will go into detail with this in a later guide.

Then navigate to your Gatsby starter project and open the .env.development file and store your publishable key in the GATSBY_STRIPE_KEY variable:

# .envGATSBY_STRIPE_KEY=<your key here>

What’s next?#

At this point we have set everything up, and the Stripe payment provider is now enabled in your Medusa project. So, go ahead and start up your medusa project, the gatsby starter, and the admin panel!

However, as Medusa allows for different payment providers in different regions (and multiple providers in each) we should first make Stripe a valid payment option in our default region. To do so, open the admin panel (http://localhost:7000) login, and navigate to Settings > Region settings > Edit Default Region. Here you should now be able to select Stripe as a payment provider:

Change payment provider

After doing this, and clicking save, we are ready to accept payments using Stripe. So, navigate to your storefront (http://localhost:8000) and go through the checkout process:

Checkout process

After doing so, you should be able to see an uncaptured payment in Stripe. Here, you navigate to the payments tab, where you should see the following (depending on your choices during the checkout process):

Uncaptured payment

To then capture the payment, navigate back to the admin panel (http://localhost:7000/), and dig into the relevant order, and capture the payment:

Capture payment

The capture is then reflected in the payment overview in Stripe as well, giving you access to all of Stripe's analytical capabilities:

Captured payment


In this guide we have setup Stripe as a payment provider giving you a fully functioning ecommerce experience! Interested in learning more? Check out the other guides and tutorials or head over to our Discord channel if you have any questions or want to become part of our community!

View plugin here