Stripe Module Provider

In this document, you’ll learn about the Stripe Module Provider and how to configure it in the Payment Module.

Register the Stripe Module Provider#

The Stripe Module Provider is installed by default in your application. To use it, add it to the array of providers passed to the Payment Module in medusa-config.ts:

medusa-config.ts
1import { Modules } from "@medusajs/framework/utils"2
3// ...4
5module.exports = defineConfig({6  // ...7  modules: [8    {9      resolve: "@medusajs/medusa/payment",10      options: {11        providers: [12          {13            resolve: "@medusajs/medusa/payment-stripe",14            id: "stripe",15            options: {16              apiKey: process.env.STRIPE_API_KEY,17            },18          },19        ],20      },21    },22  ],23})

Environment Variables#

Make sure to add the necessary environment variables for the above options in .env:

Terminal
❯STRIPE_API_KEY=<YOUR_STRIPE_API_KEY>

Module Options#

Enable Stripe Providers in a Region#

Before customers can use Stripe to complete their purchases, you must enable the Stripe payment provider(s) in the region where you want to offer this payment method.

Refer to the user guide to learn how to edit a region and enable the Stripe payment provider.

Stripe Payment Provider IDs#

When you register the Stripe Module Provider, it registers different providers, such as basic Stripe payment, Bancontact, and more.

Each provider is registered and referenced by a unique ID made up of the format pp_{identifier}_{id}, where:

• {identifier} is the ID of the payment provider as defined in the Stripe Module Provider.
• {id} is the ID of the Stripe Module Provider as set in the medusa-config.ts file. For example, stripe.

Assuming you set the ID of the Stripe Module Provider to stripe in medusa-config.ts, the Medusa application will register the following payment providers:

Setup Stripe Webhooks#

For production applications, you must set up webhooks in Stripe that inform Medusa of changes and updates to payments. Refer to Stripe's documentation on how to setup webhooks.

Webhook URL#

Medusa has a {server_url}/hooks/payment/{provider_id} API route that you can use to register webhooks in Stripe, where:

• {server_url} is the URL to your deployed Medusa application in server mode.
• {provider_id} is the ID of the provider as explained in the Stripe Payment Provider IDs section, without the pp_ prefix.

The Stripe Module Provider supports the following payment types, and the webhook endpoint URL is different for each:

Webhook Events#

When you set up the webhook in Stripe, choose the following events to listen to:

• payment_intent.amount_capturable_updated
• payment_intent.succeeded
• payment_intent.payment_failed

Useful Guides#

• Storefront guide: Add Stripe payment method during checkout.
• Integrate in Next.js Starter.
• Customize Stripe Integration in Next.js Starter.