Ecommerce with Stripe: How to guide

Feb 22, 2023 by

Justina Kingsley

Justina Kingsley

Explore the benefits of using Stripe and Medusa, and learn how to set up a complete ecommerce store with Stripe and Medusa.


In today's digital age, it's crucial for businesses to have a seamless and secure payment system in place. Using an ecommerce platform that enables the integration of third-party payment providers like Stripe will simplify the payment process for customers and enhance the overall shopping experience, thereby increasing sales.
Stripe is a widely-used payment gateway that offers a suite of payment APIs to help businesses accept payments online. Using a flexible ecommerce platform like Medusa to set up your ecommerce site could be a game changer.
Medusa provides the building blocks to create an ecommerce system with the necessary components, including processing payments and handling customer data with other advanced features that come with it.
In this tutorial, you will explore the benefits of using Stripe and Medusa, and learn how to set up a complete ecommerce store with Stripe and Medusa.

What is Stripe?

Stripe is one of the biggest payment providers supporting thousands of businesses in the United States and globally. It provides a platform for businesses to process online payments. Stripe offers tools and services for businesses to accept customer payments, including a payment gateway, a payment processor, and a suite of developer-friendly APIs.
Stripe supports a variety of payment methods, including credit cards, debit cards, Apple Pay, Google Pay, Microsoft Pay, Afterpay/Clearpay, Alipay, and ACH payments. Additionally, Stripe has fraud detection tools and can manage subscriptions and recurring payments.
Stripe is particularly popular among SMEs (Small and Medium-Sized Enterprises), developers, and online marketplaces. It is a good choice for ecommerce platforms looking to sell both locally and internationally. It provides tools for managing and analyzing transactions, as well as the ability to integrate with other software and services.

Why Use Stripe?

  • Easy Integration: Stripe offers easy integration with websites and mobile apps, allowing businesses to quickly and easily start accepting payments online.
  • Security: Stripe is compliant with industry security standards and regulations, providing customers with a secure and reliable payment experience.
  • Developer-Friendly API: Stripe is known for its developer-friendly API and robust documentation, making it a popular choice among businesses and developers of all sizes and industries.
  • Global Coverage: Stripe supports payments in over 135+ currencies and can be used in over 40 countries, allowing businesses to easily expand to new markets and accept payments from customers around the world.

What is Medusa?

Medusa is an open source, Node.ja-based, composable commerce engine. Its APIs can be integrated with frontend tools to create a scalable ecommerce store.
Medusa allows developers to build sophisticated commerce systems seamlessly. It’s great for developers who want full control over their development process. Medusa has three main components: the headless server, the admin panel, and the storefront for speed enhancement.
Medusa is a highly customizable platform that allows for seamless integration with various third-party services. This allows users to utilize the best solutions available in different areas, maximizing efficiency and optimizing their workflow.
It has various features, including multiple payment options, a shopping cart, a multi-currency feature, and third-party payment integration. Medusa commerce engine comes with a manual payment provider by default.

Why Use Medusa?

  • Advanced Ecommerce Features: Medusa provides some advanced ecommerce features such as multi-currency, automated RMA flows, and sales channels.
  • Developer-Friendly Features: Medusa has a pre-built open source codebase that developers clone. It has every feature of advanced ecommerce already built into it.
  • Flexible Backend: Medusa uses Node.js backend; it is built in such a way that developers can easily study, understand, and write new code for what they intend to achieve.
  • Third-Party Integration: Medusa supports integration with other services through plugins, which add new features and functionality to the platform. Some examples of such services are Segment, Contentful, PayPal, Algolia, and more.


To follow through this tutorial effectively, ensure you have the following:

How to Set up Medusa Ecommerce with Stripe

For this tutorial, you will use the Medusa commerce engine to build an ecommerce store; this will enable you to utilize all prebuilt features of Medusa for an easy development process. You’ll use the Medusa Server, Medusa Admin, and Medusa Storefront.

Create a Medusa Server Project

To create your new Medusa project, follow the steps below:

Install the Medusa CLI Tool

Medusa CLI gets your computer ready to run the Medusa codebase locally. You can run this command below to install it:
npm install @medusajs/medusa-cli -g

Create a New Medusa Server

Creating a new Medusa project is simple; run the command below:
medusa new my-medusa-store --seed
Copy to clipboard
is the name of the project folder, so you can edit it as you wish. If you have completed the above step successfully, switch to your new project:
cd my-medusa-store
Next, start your Medusa server with the command below:
medusa develop
Medusa runs by default on port
Copy to clipboard
. You can navigate to
Copy to clipboard
to see your store products.

How to Install Medusa Stripe Plugin

The Stripe plugin is a package in Medusa that enables Stripe payment on your project. In the root of your Medusa project, run the following command to install the Stripe plugin:
npm install medusa-payment-stripe
Next, in your
Copy to clipboard
file, add the code snippet below:
In the above code snippet, replace
Copy to clipboard
Copy to clipboard
with keys from your Stripe dashboard.

How to Configure Stripe in Medusa Server

Firstly, in
Copy to clipboard
, add the following at the end of the
Copy to clipboard
const plugins = [
// ...
resolve: `medusa-payment-stripe`,
options: {
api_key: process.env.STRIPE_API_KEY,
webhook_secret: process.env.STRIPE_WEBHOOK_SECRET,

Create Medusa Admin

Medusa Admin is a component of Medusa that allows merchants to handle all administrative functions which include product management, order management, customer management, discounts, currencies, regions, prices, settings, and more.
The steps below will guide you in creating Medusa Admin:
  1. Clone the Medusa Admin repository and switch the directory to the newly created folder:
    git clone https://github.com/medusajs/admin medusa-admin
    cd medusa-admin
  2. Run the command below to install all necessary dependencies:
    npm install
  3. Test it. Before you test the Medusa Admin, make sure your Medusa store server is running.
    npm start
By default, Medusa Admin runs on port
Copy to clipboard
; navigate to
Copy to clipboard
Medusa has default admin login details:
Copy to clipboard
as the email address and
Copy to clipboard
as the password. The default admin credentials are added because you used the
Copy to clipboard
option while installing the Medusa server.

How to Enable Stripe in a Region

Before you can use Stripe as a payment option during the checkout process of your storefront, you need to add it as a payment provider to every region in your store. Medusa Region is used to control the market in which your store operates. It supports multiple countries, payment options, and currencies.
Follow the steps below to add Stripe in Medusa Region:
1. On your Medusa Admin dashboard, go to _Settings → Regions_.
2. Click on the region you want to edit from the _Regions_ section. This enables you to edit different information and data related to the region.
3. Click on the three-dot icon at the top right of the selected region. Select _Edit Region Details_ from the dropdown. This opens a new window where you can edit the region's details.
4. Select Stripe as the only payment method from the _Payment Provider_ input field.
5. Once done, click the _Save and close_ button.
You can repeat the steps above for other regions as well.

Creating Medusa Storefront

Medusa has prebuilt storefronts in two frameworks: Next.js and Gatsby. This tutorial will focus on setting up a working storefront with Next.js and Stripe as its payment providers.
To create a Medusa Storefront, follow the steps below:
  1. Create a new Next.js project using the Medusa starter template.
    npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-medusa-storefront
  2. Switch to the newly created directory, 
    Copy to clipboard
    , and rename the template environment variable file to use environment variables in development:
    cd my-medusa-storefront
    mv .env.template .env.local

Configure Stripe in Medusa Storefront

In your
Copy to clipboard
file (or the file you’re using for your environment variables), add the following variable:
Make sure to replace
Copy to clipboard
with your Stripe Publishable Key.

Test Stripe Payment

Before you test Stripe payment in your storefront, ensure your Medusa server is running. Run the command below to start your storefront:
npm run dev
After running the above command, navigate to
Copy to clipboard
to test your storefront.
You can try adding products to your shopping cart and checkout; you should be able to pay with Stripe.

Capturing the Payment from the Admin

When a payment is successfully made by a customer from your storefront, the payment is authorized but not captured. You’ll need to capture the payment from your admin panel.
Follow the steps below to capture payments:
  1. In the admin, go to Orders ⇒ Select the particular order.
  2. Scroll down the page to Payment Card and click on Capture Payment.
Once you capture the payment, the payment status will automatically turn to Paid. Next, you can check your Stripe dashboard to view the payment.


This article explained what ecommerce is. It highlighted the features and benefits of Stripe and Medusa and showed a step-by-step guide to using Medusa ecommerce with Stripe.
You can add the following integrations to your store:
  • Segment plugin for advanced analytics and tracking,
  • Mailchimp for adding a newsletter subscription to your ecommerce store, and
  • Contentful for rich CMS functionalities such as two-way sync for the content, localization, versioning, and more.
You can learn more from Medusa Documentation.
Should you have any issues or questions related to Medusa, feel free to reach out to the Medusa team via Discord.

Share this post

Try Medusa

Spin up your environment in a few minutes.

Get started