Для интеграции платёжного провайдера ЮKassa в storefront Medusa DTC Starter от Gorgo начните с добавления необходимых UI-компонентов. Таким образом провайдер будет отображаться на странице оформления заказа наряду с другими доступными методами оплаты.

Когда покупатель выбирает ЮKassa, оформление заказа инициализирует платёжную сессию, а провайдер создаёт её на стороне ЮKassa и возвращает адрес для оплаты. Кнопка оплаты отправляет покупателя на эту страницу, где он сможет выбрать предпочтительный способ оплаты.

После завершения оплаты ЮKassa одновременно отправляет вебхук и перенаправляет покупателя обратно в витрину. То событие, которое придёт первым, завершит корзину и создаст новый заказ в Medusa.

Для витрины на Next.js необходимо внести следующие изменения:

Чтобы сделать ЮKassa доступным в качестве способа оплаты на странице оформления заказа витрины магазина, необходимо добавить её конфигурацию в маппинг платёжных провайдеров в файле с константами вашей витрины. Этот маппинг определяет, как каждый провайдер отображается в интерфейсе.

Откройте src/lib/constants.tsx и добавьте следующий код:

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}

Вы расширяете объект paymentInfoMap, добавляя в него запись pp_yookassa_yookassa. Эта запись определяет заголовок, подпись и иконку, которые будут отображаться для ЮKassa на странице оформления заказа, а также служит резервным значением, когда для локали нет перевода.

Вспомогательная функция isYookassa проверяет, принадлежит ли переданный providerId к ЮKassa. Она используется диспетчером ниже и функцией сборки данных платёжной сессии из следующего шага.

Добавьте компонент icon для ЮKassa:

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

Этот компонент передаётся как icon: <YooKassa /> в записи paymentInfoMap. Он отображает иконку способа оплаты ЮKassa на странице оформления заказа.

---

Чтобы перенаправить покупателя в ЮKassa, платёжная сессия должна быть корректно инициализирована с необходимыми параметрами, включая адрес возврата после оплаты и корзину для формирования онлайн-чеков.

Откройте тот же файл src/lib/constants.tsx и добавьте адрес возврата и функцию сборки данных сессии:

src/lib/constants.tsx
1/**
2 * Адрес, на который покупатель возвращается после оплаты на стороне провайдера.
3 * `<html lang>` хранит локаль, в которой отображалось оформление заказа, поэтому
4 * покупатель возвращается на том языке, на котором ушёл из магазина.
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    // ЮKassa формирует чек из корзины, а чеку нужны имя, email и телефон
25    // покупателя. Инициализация сессии до того, как оформление заказа собрало
26    // эти данные, создаёт платёж без чека.
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]

При инициировании платёжной сессии для ЮKassa build передаёт объект confirmation с type: "redirect" и return_url. Позже ЮKassa предоставит confirmation_url, на которое клиент должен быть перенаправлен.

Параметр return_url указывает на API-роут /api/payment-return вашей витрины и используется как для успешных, так и для неудачных попыток оплаты.

Объект cart включается в данные инициализации для формирования чека в соответствии с Федеральным законом № 54.

isReady удерживает сессию, пока в корзине не появятся email и адрес доставки, поскольку для чека нужны имя, email и телефон покупателя.

---

В витрине для каждого платёжного провайдера необходим отдельный компонент кнопки оплаты. Используя данные платёжной сессии, он перенаправляет покупателя на страницу оплаты ЮKassa. Сам заказ оформляется позже, когда покупатель вернётся через /api/payment-return, либо раньше по вебхуку, если тот придёт первым.

Создайте файл src/modules/checkout/components/payment-button/providers/yookassa.tsx и добавьте следующий код:

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 * ЮKassa принимает оплату на собственной странице. Сессия, созданная оформлением
21 * заказа, хранит адрес, куда отправить покупателя, а заказ оформляется, когда он
22 * вернётся через `/api/payment-return`, либо по вебхуку, если тот придёт раньше.
23 */
24const YookassaPaymentButton = ({
25  cart,
26  notReady,
27  label,
28  cartUpdating,
29  "data-testid": dataTestId,
30}: PaymentProviderButtonProps) => {
31  const t = useTranslations("Errors")
32  const [submitting, setSubmitting] = useState(false)
33  const [errorMessage, setErrorMessage] = useState<string | null>(null)
34
35  const handlePayment = () => {
36    const url = confirmationUrl(cart)
37
38    if (!url) {
39      setErrorMessage(t("paymentFailed"))
40      return
41    }
42
43    setSubmitting(true)
44    window.location.assign(url)
45  }
46
47  return (
48    <PaymentButtonShell
49      label={label}
50      onClick={handlePayment}
51      disabled={notReady}
52      loading={submitting || cartUpdating}
53      errorMessage={errorMessage}
54      errorTestId="yookassa-payment-error-message"
55      data-testid={dataTestId ?? "submit-order-button"}
56    />
57  )
58}
59
60export default YookassaPaymentButton

Этот компонент находит payment_session ЮKassa в активной корзине и извлекает значение data.confirmation.confirmation_url. Когда покупатель нажимает кнопку оплаты, он перенаправляется на этот URL для завершения оплаты на странице ЮKassa.

Если confirmation_url отсутствует, кнопка показывает сообщение об ошибке вместо перехода.

---

Импортируйте кнопку и isYookassa в src/modules/checkout/components/payment-button/index.tsx, затем добавьте case для неё в 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  }

Родительский компонент PaymentButton использует isYookassa, чтобы определить, нужно ли отобразить YookassaPaymentButton для текущей сессии, иначе выполнение переходит к следующей ветке.

---

После того как покупатель завершает оплату на странице ЮKassa, он перенаправляется обратно на витрину магазина. ЮKassa сообщает статус платежа и через это перенаправление, и через вебхук, поэтому общий API-роут проверяет, есть ли у корзины заказ, прежде чем оформлять его самому.

Откройте src/app/api/payment-return/route.ts со следующим содержимым:

src/app/api/payment-return/route.ts
1type ReturnContext = {
2  cartId: string
3  locale: string
4  origin: string
5}
6
7/**
8 * Обрабатывает возврат от провайдера, который принимает оплату на собственной
9 * странице и возвращает покупателя только с идентификатором корзины — ЮKassa
10 * в их числе.
11 *
12 * Вебхук провайдера и этот редирект соревнуются друг с другом, и какой из них
13 * ни пришёл бы первым, он оформляет заказ, поэтому перед оформлением
14 * проверяется, нет ли у корзины уже заказа.
15 */
16async function redirectProviderReturn({
17  cartId,
18  locale,
19  origin,
20}: ReturnContext) {
21  const cart = await sdk.client
22    .fetch<HttpTypes.StoreCartResponse>(`/store/carts/${cartId}`, {
23      method: "GET",
24      query: { fields: "id,order_link.order_id" },
25      headers: { ...(await getAuthHeaders()) },
26      cache: "no-store",
27    })
28    .then(({ cart }) => cart)
29    .catch(() => null)
30
31  if (!cart) {
32    return NextResponse.redirect(
33      `${origin}/${locale}/cart?error=payment_failed`
34    )
35  }
36
37  const orderId = (cart as unknown as { order_link?: { order_id?: string } })
38    .order_link?.order_id
39
40  if (orderId) {
41    const orderCacheTag = await getCacheTag("orders")
42    revalidateTag(orderCacheTag)
43    await removeCartId()
44
45    return NextResponse.redirect(
46      `${origin}/${locale}/order/${orderId}/confirmed`
47    )
48  }
49
50  // Покупатель отменил оплату, либо она была отклонена, поэтому он возвращается
51  // на страницу оформления заказа с нетронутой корзиной и может выбрать способ
52  // оплаты заново.
53  await setCartId(cartId)
54
55  try {
56    await placeOrder(cartId)
57  } catch (error) {
58    unstable_rethrow(error)
59
60    return NextResponse.redirect(
61      `${origin}/${locale}/checkout?error=payment_failed`
62    )
63  }
64
65  return NextResponse.redirect(
66    `${origin}/${locale}/checkout?error=payment_failed`
67  )
68}

Затем в функции GET направьте возврат ЮKassa в redirectProviderReturn:

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

Этот API-роут обрабатывает возврат от ЮKassa после попытки оплаты. Он всегда получает актуальное состояние корзины без кэша, чтобы не пропустить изменения, внесённые во время оплаты.

Если у корзины уже есть заказ, значит подтверждение уже пришло по вебхуку. API-роут обновляет кэш заказа, удаляет cookie корзины и отправляет покупателя на страницу подтверждения. Это гарантирует корректное завершение платёжного процесса и сохранение актуальных данных в витрине.

Иначе API-роут пытается оформить заказ сам. В случае успеха покупатель оказывается на странице подтверждения заказа. Если же возникает ошибка, покупатель возвращается на оформление заказа с error=payment_failed и может выбрать способ оплаты заново.

---

Добавьте pp_yookassa_yookassa в messages/ru.json и в каждую другую локаль под messages/:

messages/ru.json
1{
2  "PaymentMethods": {
3    // ...
4    "pp_yookassa_yookassa": {
5      "title": "ЮKassa",
6      "subtitle": "Карты, СБП"
7    }
8  }
9}

Если для локали нет записи, используются английские title и subtitle из paymentInfoMap в Шаге 1.

---

Полный код витрины находится в examples/payment-yookassa/apps/storefront, собранной на основе Medusa DTC Starter от Gorgo. В README примера перечислены все файлы, из которых состоит интеграция, включая бэкенд.