Command Palette

Search for a command to run...

Getting Started with YooKassa Payment

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

Requirements

Installation

yarn add medusa-payment-yookassa
# or
npm install medusa-payment-yookassa

Configuration

Add the provider configuration in your file of the Medusa Admin application:

// ...
module.exports = defineConfig({
  // ...
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "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
            },
          }
        ]
      }
    }
  ]
})

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

YOOKASSA_SHOP_ID=1234567
YOOKASSA_SECRET_KEY=live_secret_api_key

Provider Options

OptionDescriptionRequiredDefault
The SHOP_ID of YooKassaYes-
The secret key of YooKassaYes-
Default description on the payment if the context does not provide on YooKassaNo-
Automatic payment capture ( for one-step payment, for two-step payment)No
Enable receipt generation according to Russian fiscal data format (FFD)No
Enable when Atol Online FFD 1.2 sales register is used
Applicable only if = 		No
Store tax system:
- : General taxation system
- : Simplified (income)
- : Simplified (income minus expenses)
- : Single tax on imputed income
- : Single agricultural tax
- : Patent taxation system

Required if you use the Atol Online FFD 1.2 sales register
Applicable only if = 		No (Yes if you use the Atol Online FFD 1.2)-
Default VAT rate for products:
- : No VAT
- : 0%
- : 10%
- : 20%
- : 10/110
- : 20/110
- : 5%
- : 7%
- : 5/105
- : 7/107

For receips for self-employed - fixed value
Applicable only if = 		No-
Default VAT rate for shipping, same options as

Applicable only if = 		No-

Webhook Setup

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: 
    https://{YOUR_MEDUSA_DOMAIN}/hooks/payment/yookassa_yookassa
    Change with your medusa store domain.

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

Warning! YooKassa expects an response message to confirm successful webhook processing. Currently, Medusa does not natively support custom webhook response messages, but webhooks are still processed correctly without this.

OverviewStorefront Integration
Getting Started with YooKassa Payment