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

В новой версии плагина @gorgo/medusa-payment-yookassa мы перенесли настройки из medusa-config в Admin с помощью Модуля интеграций. Рассказываем, что изменилось и как обновиться.

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

Что такое Модуль интеграций?

Модуль интеграций переносит настройки плагина из кода в Admin и базу данных. Плагин объявляет, какие параметры ему нужны и как их отображать, а модуль по этому объявлению генерирует страницу настроек, хранит значения, шифрует секреты и отдаёт провалидированную конфигурацию во время выполнения.

Автору плагина не нужно писать формы, API-роуты и воркфлоу для управления настройками. Администратору магазина не нужен доступ к коду, чтобы сменить API-ключ или настроить онлайн-чеки.

Читать документацию

Было

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

medusa-config.ts
1module.exports = defineConfig({
modules: [
  {
    resolve: "@medusajs/medusa/payment",
    options: {
      providers: [
        {
          resolve: "@gorgo/medusa-payment-yookassa/providers/payment-yookassa",
          id: "yookassa",
          options: {
            shopId: process.env.YOOKASSA_SHOP_ID,
            secretKey: process.env.YOOKASSA_SECRET_KEY,
            capture: true,
            paymentDescription: "Test payment",
            useReceipt: true,
            useAtolOnlineFFD120: true,
            taxSystemCode: 1,
            taxItemDefault: 1,
            taxShippingDefault: 1,
          },
        },
      ],
    },
  },
  // ...
],
27})

Стало

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

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

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

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

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

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

стал обязательной зависимостью. Без него плагин не запустится.
Опции провайдера в больше не читаются. Параметры , , , , , и остальные игнорируются. Платёжный провайдер теперь принимает единственную опцию , которая указывает на инстанс интеграции.
Значения нужно ввести заново. Автоматического переноса из в базу данных нет, параметры заполняются один раз в Admin.
Нужен ключ шифрования. Переменная обязательна. Задайте её один раз и не меняйте, иначе сохранённые секреты станут нечитаемыми.
Пока интеграция не настроена, оплата не работает. Если обязательные параметры не заполнены или интеграция выключена, плагин вернёт ошибку вместо создания платежа. Заполните настройки сразу после обновления.

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

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

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

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

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

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

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

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

medusa-config.ts
1const YOOKASSA_INTEGRATION_ID = "yookassa-1"
2
3module.exports = defineConfig({
plugins: [
  {
    resolve: "@gorgo/medusa-integration",
    options: {
      encryptionKey: process.env.INTEGRATION_ENCRYPTION_KEY,
      providers: [
        {
          resolve: "@gorgo/medusa-payment-yookassa/providers/integration-yookassa",
          id: YOOKASSA_INTEGRATION_ID,
          options: {},
        },
      ],
    },
  },
  // Регистрируется, чтобы Admin подхватил переводы для страницы настроек
  {
    resolve: "@gorgo/medusa-payment-yookassa",
    options: {},
  },
  // ...
],
modules: [
  {
    resolve: "@medusajs/medusa/payment",
    options: {
      providers: [
        {
          resolve: "@gorgo/medusa-payment-yookassa/providers/payment-yookassa",
          id: "yookassa",
          options: {
            id: YOOKASSA_INTEGRATION_ID, // совпадает с id провайдера интеграции выше
          },
        },
      ],
    },
  },
  // ...
],
42})

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

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

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

.env

INTEGRATION_ENCRYPTION_KEY=supersecret

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

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

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

Что дальше

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

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

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