Getting Started with YooKassa Payment for Medusa

In this guide, you'll learn how to install and configure the YooKassa payment provider for Medusa.

• Medusa v2.17.2 or later
• Node.js v20 or later
• A YooKassa account – sign in or create one
• Integration Module

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

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

medusa-config.js
1// ...
2const YOOKASSA_INTEGRATION_ID = "yookassa-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-yookassa/providers/integration-yookassa",
15            id: YOOKASSA_INTEGRATION_ID,
16            options: {},
17          },
18        ],
19      },
20    },
21    {
22      resolve: "@gorgo/medusa-payment-yookassa",
23      options: {}
24    },
25  ],
26  modules: [
27    // ...
28    {
29      resolve: "@medusajs/medusa/payment",
30      options: {
31        providers: [
32          {
33            resolve: "@gorgo/medusa-payment-yookassa/providers/payment-yookassa",
34            id: "yookassa",
35            options: {
36              id: YOOKASSA_INTEGRATION_ID
37            }
38          },
39        ],
40      },
41    },
42  ],
43})

Add environment variables with your secret Encryption Key:

.env
INTEGRATION_ENCRYPTION_KEY=supersecret

To properly handle payment notifications from YooKassa, configure the webhook URL in your YooKassa account as following:

1. Navigate to your YooKassa merchant account at yookassa.ru/my/merchant/integration/http-notifications
2. Add a new webhook URL in the following format:

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

   Change {YOUR_MEDUSA_DOMAIN} with your medusa store domain.

YooKassa will send payment status updates to this URL, allowing Medusa to update the payment status accordingly.