Tutorial

How to add Stripe payment module to medusajs 2.0

Easily integrate Stripe payments into your MedusaJS 2.0 setup with this guide. Includes links to documentation, configuration examples, and video instructions. Set up webhooks, environment variables, and payment events for a seamless checkout experience in your Medusa webshop!

Rasmus Puls

Aug 30, 2024 • 3 min read

Video Instructions

Prerequisites

Before starting, ensure you have:

A deployed MedusaJS 2.0 stack (e.g., using the Railway deploy template).
A Stripe account with Test Mode enabled for testing.
Basic familiarity with MedusaJS and its configuration.

If you haven't set up your Medusa project yet, you can use the one-click deploy template for a quick start.

For Custom Projects

If you're not using the pre-configured Railway template:

Install the Stripe payment module, in your medusa backend:

npm install @medusajs/payments-stripe@latest

Add the following configuration to your medusa-config.js file:

const medusaConfig = {
 // Your other config
 modules: [
    // Your other modules here
    {
      key: Modules.PAYMENT,
      resolve: '@medusajs/payment',
      options: {
        providers: [
          {
            resolve: '@medusajs/payment-stripe',
            id: 'stripe',
            options: {
              apiKey: STRIPE_API_KEY,
              webhookSecret: STRIPE_WEBHOOK_SECRET,
            },
          },
        ],
      },
    }
  ],
};

For Railway Deploy Template Users

The Stripe module is already installed and pre-configured in the medusa-config.js file. You only need to set up environment variables.

Step 2: Set Up Environment Variables

Add the following environment variables to your backend and storefront projects:

Backend Variables

STRIPE_API_KEY: Your Stripe secret API key.
STRIPE_WEBHOOK_SECRET: The webhook secret generated in Stripe.

Storefront Variable

NEXT_PUBLIC_STRIPE_KEY: Your Stripe publishable API key (found in the Stripe dashboard).

For Railway users:

Navigate to your project in Railway.
Add these variables under the "Variables" section for both backend and storefront services.

Step 3: Create a Webhook in Stripe

Go to your Stripe dashboard.
Navigate to Developers > Webhooks and click "Add endpoint."
Use the following URL format for your webhook endpoint: https://<your-backend-url>/hooks/payment/stripe
Add the required payment events:
- payment_intent.succeeded
- payment_intent.amount_capturable_updated
- payment_intent.payment_failed
Save the webhook and copy the generated webhook secret.
Add this secret as the STRIPE_WEBHOOK_SECRET environment variable in your backend.

Step 4: Configure Payment Providers in Admin Dashboard

Log in to your Medusa Admin Dashboard.
Go to Settings > Regions.
Edit your region(s) and add "Stripe" as a payment provider.
Save changes.

Step 5: Test Your Integration

Enable Test Mode in your Stripe dashboard.
Use the test credit card number 4242 4242 4242 4242 with any valid expiration date, CVC, and postal code during checkout.
Verify that transactions are processed successfully in both the storefront and Stripe dashboard.

Step 6: Switch to Production

When ready for production:

Disable Test Mode in Stripe.
Replace test API keys with live API keys in your environment variables.
Update webhooks if necessary.

If you are having difficulties navigating the Stripe dashboard, or need help with the signup process, I have covered this in great details in another article where I was setting up Stripe for a Vendure webshop. You can refer to all the steps related to finding API keys, and creating webhooks, etc. from that guide. Visit the article bleow, and scroll to "Step 1: Stripe setup".