Getting Started with Mollie Payment for Medusa

In this guide, you'll learn how to install and configure the Mollie payment provider for Medusa, prepare your Mollie account, and set up the webhook.

• Medusa v2.17.2 or later
• Node.js v22.23.4, v24.22.1, v26.12.1 or later
• A Mollie account with a website profile. Test with the profile's test API key, and take real payments with its live API key
• Integration Module

yarn add @gorgo/medusa-integration @gorgo/medusa-payment-mollie

Add the configurations of the Integration Module provider and of the Medusa Payment Module in your medusa-config.ts file of the Medusa Admin application:

medusa-config.ts
1// ...
2const MOLLIE_INTEGRATION_ID = "mollie-1"
3
4module.exports = defineConfig({
5  // ...
6  plugins: [
7    // ...
8    {
9      resolve: "@gorgo/medusa-integration",
10      options: {
11        encryptionKey: process.env.INTEGRATION_ENCRYPTION_KEY,
12        providers: [
13          {
14            resolve: "@gorgo/medusa-payment-mollie/providers/integration-mollie",
15            id: MOLLIE_INTEGRATION_ID,
16            options: {},
17          },
18        ],
19      },
20    },
21    {
22      resolve: "@gorgo/medusa-payment-mollie",
23      options: {},
24    },
25  ],
26  modules: [
27    // ...
28    {
29      resolve: "@medusajs/medusa/payment",
30      options: {
31        providers: [
32          {
33            resolve: "@gorgo/medusa-payment-mollie/providers/payment-mollie",
34            id: "mollie",
35            options: {
36              id: MOLLIE_INTEGRATION_ID
37            }
38          },
39        ],
40      },
41    },
42  ],
43})

The payment provider registered this way gets the id pp_mollie_mollie, and its webhook route is /hooks/payment/mollie_mollie.

Add environment variables with your secret Encryption Key:

.env
INTEGRATION_ENCRYPTION_KEY=supersecret

The API key, the webhook URL and the other Mollie settings are not provider options. You enter them in Medusa Admin, as described in Manage Mollie Settings in Medusa Admin.

Each website profile in your Mollie account has two API keys. The test key starts with test_ and creates test payments, the live key starts with live_ and creates real ones. Copy the key you need from Developers → API keys in the Mollie Web App, choosing the website profile of your store.

The buyer pays on Mollie's payment page and sees there only the payment methods enabled on the profile. Enable the methods you want to offer in the Mollie Web App. In test mode a method works as soon as you enable it, even while Mollie still shows it as pending.

Test mode accepts only EUR. Add the provider to a region in euros for your tests, as described in Add Payment Provider. In live mode, the methods available to the buyer depend on the cart's currency.

Mollie calls a webhook every time a payment changes. The plugin sends the webhook URL with each payment it creates, so you don't register anything in Mollie. Enter the URL in the Webhook URL field of the Mollie settings in Medusa Admin, in the following format:

Webhook URL
https://{YOUR_MEDUSA_DOMAIN}/hooks/payment/mollie_mollie

Replace {YOUR_MEDUSA_DOMAIN} with your Medusa store domain. The settings accept only an https:// URL whose path contains /hooks/payment/mollie_.

A Mollie webhook carries only the payment's ID and no signature. The plugin reads the payment back from Mollie with your API key and acts only on what Mollie returns, so a forged notification cannot change an order. When the payment is paid, the plugin places the order even if the buyer closed the tab on Mollie's payment page. A notification about a payment your account does not have is ignored.

Mollie does not cancel an open payment the buyer has not chosen a method for, so a payment whose Medusa session was replaced stays payable on Mollie's page until it expires. If the buyer pays it anyway, no order can be placed for it, and the plugin refunds the payment in full and writes a warning to the log. A held payment of such a session is released instead.

Mollie retries a failed delivery up to 10 times over about 26 hours. It does not accept localhost as a webhook URL. During development, run the backend behind a tunnel with a public HTTPS address, as the example project does with yarn dev:tunnel.