Medusa.js ships with no payment gateway enabled by default. That is a feature, not an oversight. The payment layer is modular — you connect the processor you want, with the configuration you need, without being locked into a platform’s preferred vendor.
Here’s how payment integration works in Medusa, what it costs to implement, and what to do when your gateway isn’t on the default list.
How Medusa Handles Payments
Medusa’s payment architecture is module-based. Each gateway integrates as a Payment Provider — a plugin that registers with the Medusa payment module, handles session creation, captures, refunds, and webhook events.
The payment flow works like this: when a customer reaches checkout, Medusa creates a payment session with the selected provider. The provider returns a client secret or redirect URL. The frontend uses that to render the payment UI (Stripe Elements, PayPal buttons, etc.). On completion, the provider sends a webhook. Medusa captures the payment and creates the order.
This architecture means the payment UI lives in your storefront, not inside Medusa. You control exactly what the checkout looks like. No platform-imposed checkout pages, no third-party redirect unless the payment method requires it (like PayPal’s hosted flow).
Official Medusa Payment Plugins
Medusa maintains official plugins for the most common gateways. These are production-ready, actively maintained, and installable via npm.
Stripe
@medusajs/payment-stripe is the most widely deployed payment plugin in the Medusa ecosystem. It supports:
- Card payments (Visa, Mastercard, Amex)
- Apple Pay and Google Pay (via Stripe’s Payment Element)
- ACH bank transfers
- SEPA debit (for EU storefronts)
- Saved payment methods for returning customers
- Stripe Radar for fraud scoring
Implementation takes 4–8 hours for a developer who knows both Medusa and Stripe. The plugin is well-documented and handles webhook verification out of the box.
Stripe’s standard rate is 2.9% + $0.30 per transaction. At $500K annual volume, you can negotiate custom rates — typically 2.5% + $0.15. That difference saves $2,500/year at that volume.
PayPal
@medusajs/payment-paypal adds PayPal’s standard checkout and Pay Later options. PayPal’s 2024 market data shows 27% of US online shoppers prefer PayPal at checkout. Offering it alongside Stripe meaningfully affects conversion rates for certain demographics.
The plugin uses PayPal’s REST API. Implementation is 4–6 hours. PayPal’s fees are 3.49% + $0.49 for standard transactions — higher than Stripe, which is why many merchants add PayPal as a secondary option rather than a primary processor.
Klarna
Klarna’s buy-now-pay-later integration runs through @medusajs/payment-klarna. Klarna offers 3 payment products: Pay Now, Pay Later (30-day invoice), and Financing (installments up to 36 months).
For average order values above $150, Klarna increases conversion by 20–30% according to Klarna’s own merchant data. The merchant fee is typically 3.29% + $0.30, plus a monthly fee that varies by volume agreement.
Implementation is more involved than Stripe — 8–16 hours — because Klarna’s checkout flow involves server-side session management and a redirect-based confirmation step.
Razorpay and Mollie
For businesses serving India, medusa-payment-razorpay is the standard integration. Razorpay covers UPI, Netbanking, wallets, and cards — the full payment stack for Indian ecommerce.
For European businesses, Mollie is an increasingly popular alternative to Stripe, with strong coverage of local payment methods: iDEAL (Netherlands), Bancontact (Belgium), and Sofort (Germany/Austria). A community plugin exists and is actively maintained.
Community and Third-Party Plugins
Beyond the official plugins, Medusa’s open-source community maintains integrations for:
- Adyen — enterprise-grade payment processing for high-volume merchants
- Braintree (PayPal’s developer gateway) — used by merchants who want PayPal infrastructure with more API control
- Square — useful for merchants running both online and in-person sales
- Coinbase Commerce — for crypto payment acceptance
- Paymob — MENA region coverage
Community plugins vary in maintenance frequency. Before deploying one in production, review the GitHub repository’s last commit date, open issues, and whether it has been tested against Medusa v2.
What Happens When Your Gateway Isn’t on the List
If you need a payment gateway that doesn’t have a Medusa plugin, you build a custom Payment Provider. Medusa’s payment module exposes a clean interface: implement initiatePayment, authorizePayment, capturePayment, refundPayment, cancelPayment, and retrievePayment, and your gateway is integrated.
This is more work than installing an npm package, but less work than it sounds. A custom payment provider for a gateway with a well-documented API takes 20–40 hours of developer time. For a gateway with poor documentation or a legacy SOAP API, budget 40–80 hours.
Common gateways that require custom builds in Medusa as of early 2026: Authorize.Net, Worldpay, and various regional processors in Southeast Asia and Latin America.
Multi-Currency Payment Configuration
Medusa supports multiple currencies natively. Payment configuration per currency requires some additional setup: each region in Medusa can have its own set of payment providers and currencies.
A store selling in USD and EUR with Stripe can route both through the same Stripe account using Stripe’s multi-currency support. Payouts settle in the account’s home currency, or you can use Stripe Treasury for multi-currency balances.
Running different processors per region — Stripe for North America, Mollie for Europe — is supported. The configuration lives in Medusa’s admin, with region-specific payment provider assignment.
Subscription Payments
Out-of-the-box, Medusa v2 does not have a subscription module. Recurring billing requires either a custom implementation or a third-party plugin.
The most common approach: use Stripe Subscriptions directly. The subscription lifecycle (create, pause, cancel, upgrade) is managed via Stripe’s API, with Medusa handling the product catalog and order records. This requires custom development — typically 30–60 hours for a basic subscription implementation.
A community subscription plugin exists but is not officially maintained by the Medusa team. Evaluate carefully before relying on it for production.
Implementation Costs by Gateway
Here’s a realistic estimate of developer time for common gateway implementations:
| Gateway | Implementation Hours | Estimated Cost (at $100–150/hr) |
|---|---|---|
| Stripe (full) | 8–12 hours | $800–$1,800 |
| PayPal | 4–8 hours | $400–$1,200 |
| Klarna | 8–16 hours | $800–$2,400 |
| Adyen | 16–24 hours | $1,600–$3,600 |
| Custom gateway (documented API) | 20–40 hours | $2,000–$6,000 |
| Custom gateway (legacy API) | 40–80 hours | $4,000–$12,000 |
These are implementation costs only — not the storefront or Medusa core setup. Payment integration is part of a larger build, so in practice these hours are absorbed into total project cost.
Payment Security and PCI Compliance
Medusa does not store card data. Payment tokenization happens at the gateway level — Stripe, PayPal, Klarna each handle their own PCI-compliant environment. Medusa stores payment session IDs and status, not sensitive card information.
This means your Medusa application falls into PCI SAQ A or SAQ A-EP (if you’re using JavaScript-based payment forms that load in your domain). You are not dealing with PCI DSS Level 1 compliance unless you are processing over 6 million transactions per year.
Your infrastructure (hosting, database, file storage) still needs to meet reasonable security standards — TLS everywhere, secrets management, regular dependency updates. These are table stakes for any production Node.js application.
For a look at the full infrastructure picture, see our Medusa.js hosting and infrastructure guide.
What to Evaluate Before Choosing a Gateway
The payment gateway decision has financial consequences that compound over time. Before locking in:
Volume-based pricing: Most enterprise gateways offer negotiated rates above $100K/month. If you’re approaching that volume, get quotes from at least three processors before launch — not after.
Dispute handling: Stripe’s dispute process is developer-friendly. PayPal’s dispute process historically favors buyers in ambiguous cases. If your product category has high dispute rates (digital goods, subscriptions, travel), this matters.
Payout timing: Stripe pays out in 2 business days by default. Some gateways hold funds for 7–14 days, which affects cash flow for businesses running on thin margins.
Geographic coverage: If 30% of your customers are in Germany, iDEAL and SEPA support are table stakes. Match gateway capabilities to where your customers actually are.
For businesses evaluating Medusa against platforms with built-in payment processing, see our Medusa.js vs Shopify comparison and Medusa.js vs WooCommerce breakdown.
Testing Payments in Development
Medusa’s payment integrations can be tested entirely in sandbox mode before going live. Stripe’s test keys, PayPal’s sandbox environment, and Klarna’s playground mode all work with the Medusa plugins without modification.
The development workflow: configure test API keys in .env, use each gateway’s test card numbers, and verify the full checkout flow including webhooks. Stripe provides a CLI tool (stripe listen --forward-to localhost:9000/hooks) that forwards webhook events to your local environment without exposing a public URL. This makes local payment testing complete and reliable.
Running integration tests against real payment flows — rather than mocking the payment layer — catches webhook handling issues before they reach production. Webhook errors in production are a common source of orders getting stuck in a “pending” state. Testing the full cycle (payment initiation → webhook → order confirmation) locally prevents 80% of those issues.
Handling Payment Failures and Edge Cases
Payment failures are not edge cases. Roughly 5–15% of card transactions fail on the first attempt for legitimate cards — insufficient funds, bank-side fraud holds, expired cards, and soft declines.
Medusa’s payment flow is designed to keep the session open after a failed payment attempt, allowing the customer to retry with a different card without losing their cart. Implementing retry-friendly UX in the storefront (clear error messages, card field persistence) requires frontend implementation. Medusa provides the API scaffolding; the UX depends on how you build the checkout.
For high-value orders, Stripe’s Payment Links or 3D Secure enforcement is worth configuring. 3D Secure adds an authentication step that shifts liability for chargebacks to the card network, reducing dispute costs for merchants in regulated categories.
Webhook idempotency deserves attention. Payment webhooks can fire multiple times for the same event (network retries, provider redundancy). Medusa’s webhook handlers use event IDs to prevent duplicate order creation, but custom webhook logic needs to implement idempotency checks explicitly. Failing to do this results in double-captured payments and duplicate order records — both are operationally expensive to unwind.
FAQ
What payment gateways does Medusa.js support?
Medusa has official plugins for Stripe, PayPal, and Klarna. Community plugins cover Razorpay, Mollie, Adyen, Braintree, Square, and others. Any gateway with a REST API can be integrated with a custom Payment Provider implementation.
Does Medusa.js charge transaction fees?
No. Medusa itself charges nothing per transaction. You pay only the payment processor’s fees (e.g., Stripe’s 2.9% + $0.30) and your infrastructure costs. There is no Medusa license fee or revenue share.
How long does Stripe integration take in Medusa?
A complete Stripe integration — cards, Apple Pay, Google Pay, webhooks, saved payment methods — takes 8–12 hours of developer time. A basic card-only integration can be done in 4–6 hours.
Can Medusa.js handle buy-now-pay-later payments?
Yes, through the Klarna plugin. Afterpay/Clearpay integration is available via community plugins. Affirm integration requires custom development. BNPL availability depends on your merchant agreement with the BNPL provider, which has its own approval process.
Does Medusa support recurring billing and subscriptions?
Not natively in v2. Subscription billing requires custom development, typically built on top of Stripe Subscriptions. Budget 30–60 hours for a basic recurring billing implementation.
What happens if I need a payment gateway that Medusa doesn’t support?
You build a custom Payment Provider plugin. Medusa’s payment module interface is well-documented. A gateway with a clean REST API can be integrated in 20–40 developer hours. Legacy SOAP-based gateways take longer — 40–80 hours is a realistic estimate.
Is Medusa.js PCI compliant?
Medusa does not store card data — tokenization happens at the gateway level. Your application typically falls into PCI SAQ A compliance, which has minimal requirements. You are responsible for securing your infrastructure (TLS, secrets management, access controls), but you are not building your own payment vault.
If you’re evaluating a Medusa.js build and want to understand total project cost — including payment integration — our fixed-price packages lay out what’s included. For custom ecommerce requirements, our WooCommerce development services may also be worth reviewing depending on your stack preference.