YooKassa v2.0: settings in the Medusa Admin

We've released version 2.0 of the @gorgo/medusa-payment-yookassa plugin. Its headline change is a settings page in the Medusa Admin, built on our Integration Module. YooKassa credentials, online receipt options for fiscal law (54-FZ), and payment behavior are now filled in by a store admin directly in the Admin, with no code edits and no redeployment.

Before

Every option was set in medusa-config and environment variables. Any change meant editing code and redeploying the Medusa application:

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

After

The same options live on the Settings → Integrations → YooKassa page, split into three sections: credentials, payment behavior, and receipts. Values are stored in the database, and changes take effect as soon as you save.

What the settings page gives you

The settings page does more than repeat the old list of options.

• Secrets are encrypted at rest. The secret key is stored encrypted (AES-256-GCM) and is never sent to the browser.
• Fields appear as needed. Receipt options show up only when receipt generation is on, and the tax system is asked for only when you work with ATOL Online and FFD 1.2.
• Connection test. The Test connection button calls the YooKassa API with the credentials you entered and tells you right away whether they work.
• Several accounts at once. If your store works with more than one YooKassa account, you can create a separate integration instance for each.
• Changes without a restart. The plugin reads its settings on every operation, so a new key or a toggled auto-capture applies immediately.

Breaking changes

Version 2.0 is not compatible with 1.x in how it is configured. What to keep in mind:

• @gorgo/medusa-integration is now a required dependency. The plugin will not start without it.
• Provider options in medusa-config are no longer read. shopId, secretKey, capture, paymentDescription, useReceipt, taxSystemCode, and the rest are ignored. The payment provider now takes a single option, id, pointing at the integration instance.
• Values have to be entered again. Nothing is migrated automatically from medusa-config into the database, so you fill the options in once in the Admin.
• An encryption key is required. The INTEGRATION_ENCRYPTION_KEY variable is mandatory. Set it once and don't change it, or stored secrets become unreadable.
• Payments won't work until the integration is configured. If required options are missing or the integration is disabled, the plugin returns an error instead of creating a payment. Fill in the settings right after upgrading.

The webhook URL doesn't change, so there is nothing to reconfigure in your YooKassa account.

The 1.x setup guide stays available here.

How to upgrade

Upgrading takes a few minutes. The plugin requires Medusa v2.17.2 or newer.

Step 1. Install the Integration Module and the latest plugin version

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

Step 2. Update medusa-config

Register the integration provider under the Integration Module and link the payment provider to it through a shared identifier. The old payment provider options can be removed:

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    // Registered so Admin picks up the settings page translations
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, // matches the integration provider id above
35            },
36          },
37        ],
38      },
39    },
40    // ...
41  ],
42})

The YOOKASSA_INTEGRATION_ID constant ties the two config entries together. The module uses that identifier to find the right integration instance and hand its options to the payment provider.

Step 3. Set the encryption key

The module uses this key to encrypt secrets in the database:

INTEGRATION_ENCRYPTION_KEY=supersecret

Step 4. Fill in the settings in the Admin

1. Open Settings → Integrations → YooKassa.
2. In the Credentials section, enter the shop ID and the secret key.
3. If you need them, turn on receipt generation in the Receipts section and set auto-capture in the Behavior section.
4. Click Test connection and confirm the credentials are valid.
5. Enable the integration.

After that the YOOKASSA_SHOP_ID and YOOKASSA_SECRET_KEY environment variables can be removed. Full installation instructions and a complete option reference live in Getting Started and Managing settings.

What's next

• The 1.x line stays on npm and receives critical fixes only through the end of 2026. No new features are coming to it, so we recommend moving to 2.0.
• We keep developing the Integration Module, adding new field types and more capabilities on the settings page, and growing the integrations catalog in the Admin. It's worth updating regularly. Every release goes through unit, integration, and contract tests, and compatibility with the YooKassa API is checked daily, so you can trust new versions. We wrote separately about how our testing works.
• The rest of our providers already run on the module in beta: T-Kassa, Robokassa, ApiShip, and 1C. Stable 2.0 releases for them are coming in the next few releases.

Support and the Medusa community

Ask questions and discuss Medusa in the Telegram community, report plugin issues in the Gorgo support chat, or open Issues and Pull Requests on GitHub.