Getting Started with YooKassa Payment for Medusa

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

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

yarn add @gorgo/medusa-payment-yookassa

Add the provider configuration in your medusa-config.js file of the Medusa Admin application:

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

Add environment variables with your shop identifier shopId and a secret API key secretKey:

.env
1YOOKASSA_SHOP_ID=1234567
2YOOKASSA_SECRET_KEY=live_secret_api_key

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.