ЮKassa v2.0: настройки в Medusa Admin

Мы выпустили версию 2.0 плагина @gorgo/medusa-payment-yookassa. Главное изменение в том, что у него появился интерфейс настроек в Medusa Admin, построенный на Модуле интеграций. Доступы к ЮKassa, параметры онлайн-чеков по 54-ФЗ и поведение оплаты теперь заполняет администратор магазина прямо в Admin, без правок кода и повторного развёртывания.

Было

Все опции задавались в medusa-config и переменных окружения. Любое изменение означало правку кода и повторное развёртывание приложения Medusa:

1module.exports = defineConfig({
2  modules: [
3    {
4      resolve: "@medusajs/medusa/payment",
5      options: {
6        providers: [
7          {
8            resolve: "@gorgo/medusa-payment-yookassa/providers/payment-yookassa",
9            id: "yookassa",
10            options: {
11              shopId: process.env.YOOKASSA_SHOP_ID,
12              secretKey: process.env.YOOKASSA_SECRET_KEY,
13              capture: true,
14              paymentDescription: "Test payment",
15              useReceipt: true,
16              useAtolOnlineFFD120: true,
17              taxSystemCode: 1,
18              taxItemDefault: 1,
19              taxShippingDefault: 1,
20            },
21          },
22        ],
23      },
24    },
25    // ...
26  ],
27})

Стало

Те же опции собраны на странице Настройки → Интеграции → ЮKassa и разбиты на три секции: доступы, поведение оплаты и чеки. Значения хранятся в базе данных, а изменения вступают в силу сразу после сохранения.

Что даёт страница настроек

Страница настроек не просто повторяет прежний список опций.

• Секреты шифруются в базе. Секретный ключ хранится в зашифрованном виде (AES-256-GCM) и не передаётся в браузер.
• Поля показываются по необходимости. Параметры чеков появляются, только если включено их формирование, а система налогообложения запрашивается только при работе с АТОЛ Онлайн и ФФД 1.2.
• Проверка соединения. Кнопка «Проверить соединение» обращается к API ЮKassa с введёнными доступами и сразу показывает, рабочие они или нет.
• Несколько аккаунтов сразу. Если магазин работает с несколькими аккаунтами ЮKassa, для каждого можно завести отдельный инстанс интеграции.
• Изменения без перезапуска. Плагин читает настройки при каждой операции, поэтому новый ключ или переключённое автосписание применяются сразу.

Критические изменения

Версия 2.0 несовместима с 1.x по способу настройки. Что нужно учесть:

• @gorgo/medusa-integration стал обязательной зависимостью. Без него плагин не запустится.
• Опции провайдера в medusa-config больше не читаются. Параметры shopId, secretKey, capture, paymentDescription, useReceipt, taxSystemCode и остальные игнорируются. Платёжный провайдер теперь принимает единственную опцию id, которая указывает на инстанс интеграции.
• Значения нужно ввести заново. Автоматического переноса из medusa-config в базу данных нет, параметры заполняются один раз в Admin.
• Нужен ключ шифрования. Переменная INTEGRATION_ENCRYPTION_KEY обязательна. Задайте её один раз и не меняйте, иначе сохранённые секреты станут нечитаемыми.
• Пока интеграция не настроена, оплата не работает. Если обязательные параметры не заполнены или интеграция выключена, плагин вернёт ошибку вместо создания платежа. Заполните настройки сразу после обновления.

Адрес вебхука не меняется, перенастраивать личный кабинет ЮKassa не нужно.

Руководство по настройке версии 1.x остаётся доступным здесь.

Как обновиться

Обновление занимает несколько минут. Плагину требуется Medusa v2.17.2 или новее.

Шаг 1. Установите Модуль интеграций и последнюю версию плагина

npm install @gorgo/medusa-integration @gorgo/medusa-payment-yookassa@latest

Шаг 2. Обновите medusa-config

Зарегистрируйте провайдер интеграции в Модуле интеграций и свяжите с ним платёжный провайдер через общий идентификатор. Прежние опции платёжного провайдера можно удалить:

1const YOOKASSA_INTEGRATION_ID = "yookassa-1"
2
3module.exports = defineConfig({
4  plugins: [
5    {
6      resolve: "@gorgo/medusa-integration",
7      options: {
8        encryptionKey: process.env.INTEGRATION_ENCRYPTION_KEY,
9        providers: [
10          {
11            resolve: "@gorgo/medusa-payment-yookassa/providers/integration-yookassa",
12            id: YOOKASSA_INTEGRATION_ID,
13            options: {},
14          },
15        ],
16      },
17    },
18    // Регистрируется, чтобы Admin подхватил переводы для страницы настроек
19    {
20      resolve: "@gorgo/medusa-payment-yookassa",
21      options: {},
22    },
23    // ...
24  ],
25  modules: [
26    {
27      resolve: "@medusajs/medusa/payment",
28      options: {
29        providers: [
30          {
31            resolve: "@gorgo/medusa-payment-yookassa/providers/payment-yookassa",
32            id: "yookassa",
33            options: {
34              id: YOOKASSA_INTEGRATION_ID, // совпадает с id провайдера интеграции выше
35            },
36          },
37        ],
38      },
39    },
40    // ...
41  ],
42})

Константа YOOKASSA_INTEGRATION_ID связывает две записи в конфигурации. По этому идентификатору модуль находит нужный инстанс интеграции и возвращает платёжному провайдеру его параметры.

Шаг 3. Задайте ключ шифрования

Этим ключом модуль шифрует секреты в базе данных:

INTEGRATION_ENCRYPTION_KEY=supersecret

Шаг 4. Заполните настройки в Admin

1. Откройте Настройки → Интеграции → ЮKassa.
2. В секции Доступы укажите идентификатор магазина и секретный ключ.
3. При необходимости включите формирование чеков в секции Чеки и настройте автосписание в секции Поведение.
4. Нажмите Проверить соединение и убедитесь, что доступы верны.
5. Включите интеграцию.

После этого переменные окружения YOOKASSA_SHOP_ID и YOOKASSA_SECRET_KEY можно удалить. Полное описание установки и всех параметров есть в разделах Начало работы и Управление настройками.

Что дальше

• Версия 1.x остаётся в npm и до конца 2026 года получает только критические исправления. Новых функций в ней не будет, поэтому рекомендуем перейти на 2.0.
• Модуль интеграций мы продолжаем развивать, добавляем новые типы полей и возможности страницы настроек, расширяем каталог интеграций в Admin. Обновляться стоит регулярно. Каждый релиз проходит юнит-, интеграционные и контрактные тесты, а совместимость с API ЮKassa проверяется ежедневно, так что новым версиям можно доверять. Как устроено тестирование, мы рассказывали отдельно.
• Остальные наши провайдеры уже работают на модуле в бета-версиях: Т-Касса, Robokassa, ApiShip и 1С. Стабильные версии 2.0 для них выйдут в ближайших релизах.

Поддержка и сообщество Medusa

Задавайте вопросы и обсуждайте Medusa в Telegram-сообществе, пишите о проблемах с плагином в чат поддержки Gorgo или открывайте Issues и Pull Requests на GitHub.