To integrate the YooKassa payment provider into the Medusa DTC Starter by Gorgo storefront, start by adding the required UI components, so the provider is displayed on the checkout page alongside other available payment methods.

When the customer selects YooKassa, the checkout initiates a payment session, and the provider creates it on YooKassa's side and returns the payment address. The payment button then sends the customer there, where they can choose a payment method.

Once the payment is completed, YooKassa concurrently sends a webhook and redirects the customer back to the storefront. Whichever event arrives first completes the cart and creates a new order in Medusa.

For the storefront on Next.js, you need to make the following changes:

To make YooKassa available as a payment method on the storefront checkout page, you must add its configuration to the payment provider mapping in your storefront's constants file. This mapping determines how each payment provider is displayed in the UI.

Open src/lib/constants.tsx and add the following code:

src/lib/constants.tsx
1export type PaymentInfo = {
2  title: string
3  subtitle?: string
4  icon: React.JSX.Element
5}
6
7export const paymentInfoMap: Record<string, PaymentInfo> = {
8  // ...
9  pp_yookassa_yookassa: {
10    title: "YooKassa",
11    subtitle: "Cards, SBP",
12    icon: <YooKassa />,
13  },
14  // ...
15}
16
17// ...
18
19export const isYookassa = (providerId?: string) => {
20  return providerId?.startsWith("pp_yookassa")
21}

You extend the paymentInfoMap object to include a pp_yookassa_yookassa entry. This entry defines the title, the subtitle, and the icon that will be shown for YooKassa on the checkout page, and also serves as the fallback when a locale carries no translation.

The helper function isYookassa checks whether a given providerId belongs to YooKassa. It's used by the dispatcher below and by the session data builder in the next step.

Add the icon component for YooKassa:

src/modules/common/icons/yookassa.tsx
1import type React from "react"
2
3import type { IconProps } from "types/icon"
4
5const YooKassa: React.FC<IconProps> = ({
6  size = "16",
7  color: _color,
8  ...attributes
9}) => {
10  return (
11    <svg
12      width={size}
13      height={size}
14      viewBox="73 129 366 254"
15      role="img"
16      fill="none"
17      xmlns="http://www.w3.org/2000/svg"
18      {...attributes}
19    >
20      <title>YooKassa icon</title>
21      <path
22        fillRule="evenodd"
23        clipRule="evenodd"
24        d="M178.511 255.527C178.701 185.824 236.332 129 308.751 129C380.466 129 ..."
25        fill="#0070F0"
26      />
27    </svg>
28  )
29}
30
31export default YooKassa

This component is passed as icon: <YooKassa /> in the paymentInfoMap entry. It displays the icon for the YooKassa payment method on the checkout page.

---

To redirect a customer to YooKassa, the payment session must be properly initialized with the required parameters, including the return address for the post-payment callback and the shopping cart for generating receipts.

Open the same src/lib/constants.tsx and add the return address and the session data builder:

src/lib/constants.tsx
1/**
2 * The address the customer comes back to after paying on the provider's own
3 * page. `<html lang>` carries the locale the checkout was rendered in, so the
4 * customer returns to the language they left the shop with.
5 */
6const paymentReturnUrl = (providerId: string, cartId: string) => {
7  const origin =
8    typeof window === "undefined" ? getBaseURL() : window.location.origin
9  const locale =
10    typeof document === "undefined"
11      ? defaultLocale
12      : document.documentElement.lang || defaultLocale
13
14  return `${origin}/api/payment-return?provider=${providerId}&cart_id=${cartId}&locale=${locale}`
15}
16
17const paymentSessionDataBuilders: Array<{
18  test: (providerId?: string) => boolean | undefined
19  isReady?: (cart: HttpTypes.StoreCart) => boolean
20  build: (cart: HttpTypes.StoreCart) => Record<string, unknown>
21}> = [
22  {
23    test: (providerId) => isYookassa(providerId),
24    // YooKassa builds a receipt out of the cart, and the receipt needs the
25    // buyer's name, email and phone. Initiating the session before the checkout
26    // collected them creates a payment without one.
27    isReady: (cart) => Boolean(cart.email && cart.shipping_address),
28    build: (cart) => ({
29      confirmation: {
30        type: "redirect",
31        return_url: paymentReturnUrl("yookassa", cart.id),
32      },
33      cart,
34    }),
35  },
36]

When initiating a payment for YooKassa, build passes a confirmation object with type: "redirect" and a return_url. YooKassa will later provide a confirmation_url to which the customer should be redirected.

The return_url points back to your storefront's /api/payment-return route and is used for both successful and failed payment attempts.

The cart object is included to build a receipt compliant with Federal Law No. 54.

isReady holds the session back until the cart carries an email and a shipping address, since the receipt needs the buyer's name, email and phone.

---

The storefront needs a dedicated payment button component for each payment provider. Using the payment session data, it sends the customer to the YooKassa payment page. The order itself is placed later, when the customer comes back through /api/payment-return, or earlier through the webhook if that arrives first.

Create src/modules/checkout/components/payment-button/providers/yookassa.tsx and add the following code:

src/modules/checkout/components/payment-button/providers/yookassa.tsx
1"use client"
2
3import type { HttpTypes } from "@medusajs/types"
4import { useTranslations } from "next-intl"
5import { useState } from "react"
6import { PaymentButtonShell, type PaymentProviderButtonProps } from "../shared"
7
8const confirmationUrl = (cart: HttpTypes.StoreCart) => {
9  const session = cart.payment_collection?.payment_sessions?.find((s) =>
10    s.provider_id.startsWith("pp_yookassa")
11  )
12  const confirmation = session?.data?.confirmation as
13    | { confirmation_url?: string }
14    | undefined
15
16  return confirmation?.confirmation_url
17}
18
19/**
20 * YooKassa collects the payment on its own page. The session the checkout
21 * created carries the address to send the customer to, and the order is placed
22 * once they come back through `/api/payment-return` — or by the webhook, if
23 * that arrives first.
24 */
25const YookassaPaymentButton = ({
26  cart,
27  notReady,
28  label,
29  cartUpdating,
30  "data-testid": dataTestId,
31}: PaymentProviderButtonProps) => {
32  const t = useTranslations("Errors")
33  const [submitting, setSubmitting] = useState(false)
34  const [errorMessage, setErrorMessage] = useState<string | null>(null)
35
36  const handlePayment = () => {
37    const url = confirmationUrl(cart)
38
39    if (!url) {
40      setErrorMessage(t("paymentFailed"))
41      return
42    }
43
44    setSubmitting(true)
45    window.location.assign(url)
46  }
47
48  return (
49    <PaymentButtonShell
50      label={label}
51      onClick={handlePayment}
52      disabled={notReady}
53      loading={submitting || cartUpdating}
54      errorMessage={errorMessage}
55      errorTestId="yookassa-payment-error-message"
56      data-testid={dataTestId ?? "submit-order-button"}
57    />
58  )
59}
60
61export default YookassaPaymentButton

This component locates the YooKassa payment_session in the active cart and extracts data.confirmation.confirmation_url. When the customer clicks the payment button, they're redirected to this URL to complete the payment on the YooKassa page.

If the confirmation_url is missing, the button shows an error message instead of navigating anywhere.

---

Import the button and isYookassa in src/modules/checkout/components/payment-button/index.tsx, then add a case for it in the dispatcher's switch:

src/modules/checkout/components/payment-button/index.tsx
1import {
2  isManual,
3  isPaymentSessionReady,
4  isStripeLike,
5  isYookassa,
6} from "@lib/constants"
7// ...
8import YookassaPaymentButton from "./providers/yookassa"
9
10// ...
11
12  switch (true) {
13    // ...
14    case isYookassa(activePaymentMethod):
15      return <YookassaPaymentButton {...providerProps} />
16    default:
17      // ...
18  }

The parent PaymentButton uses isYookassa to determine whether to display YookassaPaymentButton for the current session; otherwise it falls through to the next case.

---

After the customer completes payment on the YooKassa page, they're redirected back to the storefront. YooKassa reports the payment status through both this redirect and a webhook, so the shared route checks the cart for an order before placing one itself.

Open src/app/api/payment-return/route.ts with the following content:

src/app/api/payment-return/route.ts
1type ReturnContext = {
2  cartId: string
3  locale: string
4  origin: string
5}
6
7/**
8 * Comes back from a provider that takes the customer to its own payment page
9 * and returns them with nothing but the cart id — YooKassa among them.
10 *
11 * The provider's webhook and this redirect race each other, and whichever
12 * arrives first places the order, so the cart is checked for an order before
13 * one is placed.
14 */
15async function redirectProviderReturn({
16  cartId,
17  locale,
18  origin,
19}: ReturnContext) {
20  const cart = await sdk.client
21    .fetch<HttpTypes.StoreCartResponse>(`/store/carts/${cartId}`, {
22      method: "GET",
23      query: { fields: "id,order_link.order_id" },
24      headers: { ...(await getAuthHeaders()) },
25      cache: "no-store",
26    })
27    .then(({ cart }) => cart)
28    .catch(() => null)
29
30  if (!cart) {
31    return NextResponse.redirect(
32      `${origin}/${locale}/cart?error=payment_failed`
33    )
34  }
35
36  const orderId = (cart as unknown as { order_link?: { order_id?: string } })
37    .order_link?.order_id
38
39  if (orderId) {
40    const orderCacheTag = await getCacheTag("orders")
41    revalidateTag(orderCacheTag)
42    await removeCartId()
43
44    return NextResponse.redirect(
45      `${origin}/${locale}/order/${orderId}/confirmed`
46    )
47  }
48
49  // The customer backed out or the payment was declined, so they land back on
50  // the checkout with their cart intact and can pick a method again.
51  await setCartId(cartId)
52
53  try {
54    await placeOrder(cartId)
55  } catch (error) {
56    unstable_rethrow(error)
57
58    return NextResponse.redirect(
59      `${origin}/${locale}/checkout?error=payment_failed`
60    )
61  }
62
63  return NextResponse.redirect(
64    `${origin}/${locale}/checkout?error=payment_failed`
65  )
66}

Then route YooKassa's return to redirectProviderReturn, in GET:

src/app/api/payment-return/route.ts
1if (provider === "yookassa") {
2    return redirectProviderReturn({ cartId, locale, origin })
3  }

This route handles the return from YooKassa after a payment attempt. It always fetches the cart's latest state, uncached, so it doesn't miss changes made during payment.

If the cart already has an order, the confirmation already arrived through the webhook. The route revalidates the order cache, removes the cart cookie, and sends the customer to the confirmation page. This ensures a consistent post-payment experience while keeping storefront data up to date.

Otherwise the route tries to place the order itself. If successful, the customer ends up on the order confirmation page. If an error happens, the customer is sent back to the checkout with error=payment_failed so they can pick a method again.

---

Add pp_yookassa_yookassa to messages/en.json and to every other locale under messages/:

messages/en.json
1{
2  "PaymentMethods": {
3    // ...
4    "pp_yookassa_yookassa": {
5      "title": "YooKassa",
6      "subtitle": "Cards, SBP"
7    }
8  }
9}

A locale missing an entry falls back to the English title and subtitle from paymentInfoMap in Step 1.

---

The complete storefront is located at examples/payment-yookassa/apps/storefront, built on the Medusa DTC Starter by Gorgo. The example's own README lists every file the integration consists of, backend included.