Adyen Payments for Medusa

A backend Adyen payment provider for Medusa, built to handle real-world asynchronous payment flows Built by minimall LLC - engineers with over a decade of experience in commerce, marketplaces, and production payment systems
View Source on GitHub Install from NPM Work with minimall
Designed for teams integrating Adyen Advanced flows into Medusa-powered commerce systems

This page assumes familiarity with Adyen and Medusa. If either platform is new to you, the following resources provide quick context: Adyen | Medusa

The Medusa-Adyen integration problem

Medusa's payment module is designed around synchronous payment operations. When a payment operation occurs, the system expects an immediate and definitive outcome. Adyen's payment platform works differently. Most payment operations are asynchronous: API calls are acknowledged, but the final outcome is delivered later via webhook notifications. This mismatch creates a real integration challenge. If asynchronous payment results are treated as final, Medusa's internal payment state can drift from Adyen's actual source of truth. That drift can lead to incorrect order states, premature fulfillment, or missed failures. Bridging this gap requires more than forwarding API calls. It requires explicit state reconciliation, careful handling of intermediate states, and a webhook-driven model that aligns Medusa's expectations with Adyen's behavior.

Webhook-driven reconciliation

This plugin approaches the Medusa-Adyen integration as a state-synchronization problem rather than a simple request-response problem. Medusa's payment workflows assume that payment operations complete immediately. To remain compatible with this assumption, the plugin responds to Medusa as though each payment operation has succeeded once Adyen acknowledges receipt of the corresponding API request, allowing Medusa's workflows to proceed without modification. Under the hood, those acknowledgements are treated as intermediate states. Final payment outcomes are determined asynchronously through Adyen webhook notifications, which serve as the authoritative source of truth. When a webhook reports a failure or correction, the plugin intervenes and reconciles Medusa's internal payment records accordingly. This design allows the plugin to satisfy Medusa's synchronous expectations while still respecting Adyen's asynchronous payment model, enabling accurate state correction without coupling frontend behavior or checkout UX to backend payment timing.

Production realities and compromises

This plugin is not a drop-in, production-safe abstraction for all Medusa and Adyen use cases. The underlying challenge is structural. Medusa's payment module is designed around synchronous workflows, while Adyen's payment platform relies on asynchronous confirmation via webhooks. Although this plugin reconciles that mismatch in a controlled way, it does so by operating close to Medusa's internal payment models. As a result, the plugin is tightly coupled to specific Medusa versions and internal payment module behavior. Changes to Medusa's internal APIs or data models may require corresponding updates to the plugin, and compatibility across Medusa versions is not guaranteed. There are also operational implications. Because payment operations may appear successful before webhook confirmation is received, merchants must ensure that irreversible business actions, such as order fulfillment or shipment, are gated on webhook-confirmed payment states rather than initial acknowledgements. This trade-off is intentional. The plugin prioritizes correctness and state reconciliation over superficial simplicity, but it requires a clear understanding of Medusa's payment lifecycle and Adyen's asynchronous behavior to be used safely in production.
PCI compliance considerations
Adyen's Advanced flow, when integrated with Medusa's payment module, introduces important PCI compliance considerations. Adyen's Advanced flow expects sensitive payment data during payment authorizations, which are initiated from the backend. While this data originates on the frontend, where the shopper provides their payment details, Medusa's payment module does not allow frontend-supplied data to be transmitted at the moment a payment is authorized. However, it does make payment session data accessible at that point. To reconcile this, the plugin captures the required payment data earlier in the flow and stores it within the Medusa payment session so it can be used during authorization. This allows the integration to function correctly, but it also means that sensitive payment-related data will persist within merchant-controlled infrastructure. The plugin minimizes the retention period by replacing the payment session data once the authoritative webhook has been received and processed. This does not remove PCI obligations from the merchant. Teams using this plugin must ensure their frontend, backend, and infrastructure are designed and operated with appropriate PCI compliance controls in place. These constraints are inherent to reconciling Adyen's Advanced payment flow with Medusa's payment model. The plugin makes this boundary explicit and manageable, but production use requires informed architectural and compliance decisions. In practice, this means the plugin is best deployed by teams with explicit payment ownership, operational discipline, and clear compliance responsibilities.

Capabilities

  • Support for Adyen Advanced payment flows
  • Server-side payment session creation and management
  • Authorization, capture, cancellation, and refund operations
  • Webhook-driven reconciliation of final payment outcomes
  • Synchronization of Medusa payment collections, payments, captures, and refunds
  • Retry handling for transient Adyen API failures
  • Frontend-agnostic design compatible with Web Components, Drop-in, and custom integrations

When to use this plugin

This plugin is a good fit if:

  • You are building a Medusa-based commerce system that integrates with Adyen's Advanced payment flows
  • You require backend control over payment authorization, capture, refunds, and webhook processing
  • You are comfortable operating close to Medusa's payment module and internal payment lifecycle
  • You explicitly gate order fulfillment and other irreversible actions on webhook-confirmed payment states
  • You value correctness and state reconciliation over simplified, optimistic payment assumptions
  • You understand and accept the PCI compliance implications of handling payment data within your backend infrastructure

This plugin may not be a good fit if:

  • You need a fully abstracted, plug-and-play payment provider with minimal operational awareness
  • You expect immediate, final payment results from API calls alone
  • You are unable to rely on or correctly process Adyen webhook notifications
  • You require guaranteed compatibility across multiple Medusa versions without adjustment
  • You are looking for a frontend checkout implementation rather than a backend payment provider
This plugin is best suited for teams that are prepared to treat payments as a distributed, event-driven system, and to own the operational and compliance responsibilities that come with it.

Open source and commercial support

This plugin is released as open-source software under the MIT license. As permitted by the MIT license, the software is provided “as is”, without warranty of any kind, and minimall LLC assumes no liability for its use. The goal of open-sourcing this plugin is transparency and shared understanding. Payment integrations are complex, and making the implementation visible allows teams to evaluate trade-offs, audit behavior, and build confidence in how payment state is handled. minimall LLC provides commercial services around Adyen and other payment integrations across Medusa and other TypeScript-based commerce platforms.
Our commercial services include:
  • Design and implementation of Adyen payment integrations for Medusa and other commerce platforms
  • Production hardening, risk assessment, and payment state validation
  • Customization for specific platform versions, business workflows, and operational requirements
  • Ongoing maintenance, upgrades, and long-term support for payment infrastructure
minimall LLC is actively pursuing closer collaboration with payment providers, including formal integration and solution partnerships. For teams building or operating payment-critical commerce systems, this offers access to practical experience, architectural guidance, and production-focused support beyond what a standalone plugin can provide.

Resources and next steps

If you are evaluating Adyen for a Medusa-based commerce system, this plugin can serve as a reference implementation, a starting point, or a production foundation with appropriate operational safeguards. For teams that need help designing, implementing, or operating payment-critical systems, minimall LLC provides advisory and hands-on engineering support across Medusa and other TypeScript-based commerce platforms.