Начало работы с Mollie для Medusa

В этом руководстве вы узнаете, как установить и настроить платёжный провайдер Mollie для Medusa, подготовить аккаунт Mollie и подключить вебхук.

• Medusa v2.17.2 или новее
• Node.js v22.23.4, v24.22.1, v26.12.1 или новее
• Аккаунт Mollie с профилем сайта. Для тестов подойдёт тестовый API-ключ профиля, для настоящих платежей нужен его live-ключ
• Модуль интеграций

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

Добавьте конфигурацию провайдера Модуля интеграций и Платёжного модуля Medusa в файл medusa-config.ts приложения Medusa Admin:

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})

Платёжный провайдер, зарегистрированный так, получает id pp_mollie_mollie и принимает вебхуки на роуте /hooks/payment/mollie_mollie.

Добавьте переменную окружения с секретным ключом шифрования:

.env
INTEGRATION_ENCRYPTION_KEY=supersecret

API-ключ, адрес вебхука и остальные настройки Mollie не входят в параметры провайдера. Введите их в Medusa Admin, как описано в разделе Управление настройками Mollie в Medusa Admin.

У каждого профиля сайта в аккаунте Mollie два API-ключа. Тестовый начинается с test_ и работает в тестовом режиме, live-ключ начинается с live_ и создаёт настоящие платежи. Скопируйте нужный ключ в разделе Developers → API keys в Mollie Web App, выбрав профиль сайта вашего магазина.

Покупатель платит на платёжной странице Mollie и видит там только способы оплаты, включённые в профиле. Включите нужные способы в Mollie Web App. В тестовом режиме способ работает сразу после включения, даже если Mollie ещё показывает его на проверке.

Тестовый режим принимает только EUR. Для тестов добавьте провайдер в регион с евро, как описано в разделе Добавление платёжного провайдера. В live-режиме набор способов оплаты, доступных покупателю, зависит от валюты корзины.

Mollie вызывает вебхук при каждом изменении платежа. Адрес вебхука плагин передаёт с каждым созданным платежом, поэтому регистрировать что-либо в Mollie не нужно. Укажите адрес в поле Адрес вебхука настроек Mollie в Medusa Admin в следующем формате:

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

Замените {YOUR_MEDUSA_DOMAIN} на домен вашего магазина Medusa. Настройки принимают только адрес на https://, в пути которого есть /hooks/payment/mollie_.

Вебхук Mollie содержит только ID платежа и не подписан. Плагин перечитывает платёж в Mollie вашим API-ключом и действует только по ответу Mollie, поэтому поддельное уведомление заказ не изменит. Когда платёж оплачен, плагин создаёт заказ, даже если покупатель закрыл вкладку на платёжной странице Mollie. Уведомление о платеже, которого нет в вашем аккаунте, плагин пропускает.

Открытый платёж, в котором покупатель ещё не выбрал способ оплаты, Mollie не отменяет. Поэтому платёж, чья сессия в Medusa была заменена, остаётся доступным для оплаты на странице Mollie, пока не истечёт. Если покупатель всё же его оплатит, заказ для него создать нельзя, и плагин возвращает платёж целиком и пишет предупреждение в лог. Заблокированную сумму такой сессии плагин вместо возврата разблокирует.

Mollie повторяет неудачную доставку до 10 раз в течение примерно 26 часов. Адрес на localhost Mollie не принимает. На время разработки запускайте бэкенд за туннелем с публичным HTTPS-адресом, как это делает пример проекта командой yarn dev:tunnel.