@medusajs/payment-stripe
Documentation | Website
Building blocks for digital commerce
Stripe Payment Module Provider for Medusa: processes payments with Stripe Payment Intents, including cards and local payment methods such as iDEAL, Bancontact, BLIK, Przelewy24, PromptPay, giropay, and OXXO. Use it to accept payments through Stripe in your checkout. It ships with @medusajs/medusa and is registered through the @medusajs/medusa/payment-stripe path.
At a glance
| Package | @medusajs/payment-stripe |
| Type | Module Provider (Payment Module) |
| Provider ID | One per payment method, see Payment provider services |
| Registered by default | No |
| Import from | @medusajs/medusa/payment-stripe |
Payment provider services
Registering the provider once adds all of the following payment providers. The registered ID has the format pp_{identifier}_{id}, where {id} is the id you set in medusa-config.ts. With id: "stripe":
| Identifier | Payment method | Registered ID |
|---|---|---|
stripe |
Cards and other methods enabled on the Payment Intent | pp_stripe_stripe |
stripe-bancontact |
Bancontact | pp_stripe-bancontact_stripe |
stripe-blik |
BLIK | pp_stripe-blik_stripe |
stripe-giropay |
giropay | pp_stripe-giropay_stripe |
stripe-ideal |
iDEAL | pp_stripe-ideal_stripe |
stripe-przelewy24 |
Przelewy24 | pp_stripe-przelewy24_stripe |
stripe-promptpay |
PromptPay | pp_stripe-promptpay_stripe |
stripe-oxxo |
OXXO (always captured automatically) | pp_stripe-oxxo_stripe |
Enable the ones you want on each region, for example from the Medusa Admin.
Installation
No installation needed. The provider is a dependency of @medusajs/medusa.
Usage
Register the provider in the Payment Module's providers array in medusa-config.ts:
import { defineConfig } from "@medusajs/framework/utils"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/payment",
options: {
providers: [
{
resolve: "@medusajs/medusa/payment-stripe",
id: "stripe",
options: {
apiKey: process.env.STRIPE_API_KEY,
webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
},
},
],
},
},
],
})
In production, register a Stripe webhook pointing to {server_url}/hooks/payment/{provider_id}, where {provider_id} is the registered ID without the pp_ prefix, such as stripe_stripe. Without webhookSecret, webhook signature verification fails and payment flows that depend on webhooks (such as 3D Secure or async capture) can't update orders.
Configuration
| Option | Type | Description | Default |
|---|---|---|---|
apiKey |
string |
Required. Your Stripe secret API key. | - |
apiVersion |
string |
The Stripe API version requests use. From 2026-07-29, payment method types are sent as allowed_payment_method_types instead of payment_method_types. |
2024-04-10 |
webhookSecret |
string |
The Stripe webhook signing secret. A warning is logged if it's missing. | - |
capture |
boolean |
Capture payments immediately instead of only authorizing them. | false |
automaticPaymentMethods |
boolean |
Set automatic_payment_methods: { enabled: true } on Payment Intents. |
false |
paymentMethodConfiguration |
string |
A Stripe payment method configuration ID applied to Payment Intents that don't set specific payment method types. | - |
paymentDescription |
string |
Default Payment Intent description when the payment context doesn't provide one. | - |
oxxoExpiresDays |
number |
Days before an OXXO payment expires. | 3 |
asyncPaymentMethodTypes |
string[] |
Stripe payment method types treated as asynchronous, which can create an order while the payment is pending. |
[] (all synchronous) |
| Environment variable | Description |
|---|---|
STRIPE_API_KEY |
Value for apiKey, as used in the example above. |
STRIPE_WEBHOOK_SECRET |
Value for webhookSecret, as used in the example above. |