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

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

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

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

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

Откройте 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_tkassa_tkassa: {
10    title: "T-Kassa",
11    subtitle: "Cards, SBP",
12    icon: <TKassa />,
13  },
14  // ...
15}
16
17// ...
18
19export const isTkassa = (providerId?: string) => {
20  return providerId?.startsWith("pp_tkassa")
21}

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

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

Добавьте компонент icon для Т-Кассы:

src/modules/common/icons/tkassa.tsx
1import type React from "react"
2
3import type { IconProps } from "types/icon"
4
5const TKassa: React.FC<IconProps> = ({
6  size = "16",
7  color: _color,
8  ...attributes
9}) => {
10  return (
11    <svg
12      width={size}
13      height={size}
14      viewBox="50 60 200 200"
15      role="img"
16      fill="none"
17      xmlns="http://www.w3.org/2000/svg"
18      {...attributes}
19    >
20      <title>T-Kassa icon</title>
21      <path
22        d="M50 60H250V160.313C250 186.028 236.244 209.791 213.914 222.651L150 259.457L86.0859 222.651C63.7557 209.791 50 186.028 50 160.313V60Z"
23        fill="#FFDD2D"
24      />
25      <path
26        fillRule="evenodd"
27        clipRule="evenodd"
28        d="M104.76 112.797V143.996C109.038 139.178 116.816 135.918 125.709 135.918H135.374V172.187C135.374 181.836 132.745 190.282 128.844 194.927H170.883C166.99 190.277 164.368 181.842 164.368 172.205V135.918H174.033C182.926 135.918 190.704 139.178 194.982 143.996V112.797H104.76Z"
29        fill="#333333"
30      />
31    </svg>
32  )
33}
34
35export default TKassa

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

---

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

Откройте тот же файл 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) => isTkassa(providerId),
24    // Т-Касса формирует чек из корзины, а чеку нужны email и телефон
25    // покупателя. Инициализация сессии до того, как оформление заказа собрало
26    // эти данные, создаёт платёж без чека.
27    isReady: (cart) => Boolean(cart.email && cart.shipping_address),
28    build: (cart) => {
29      const returnUrl = paymentReturnUrl("tkassa", cart.id)
30
31      return {
32        SuccessURL: returnUrl,
33        FailURL: returnUrl,
34        cart,
35      }
36    },
37  },
38]

При инициализации платежа для Т-Касса build передаёт SuccessURL и FailURL, оба указывающие на один и тот же адрес возврата.

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

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

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

---

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

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

src/modules/checkout/components/payment-button/providers/tkassa.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 paymentUrl = (cart: HttpTypes.StoreCart) => {
9  const session = cart.payment_collection?.payment_sessions?.find((s) =>
10    s.provider_id.startsWith("pp_tkassa")
11  )
12
13  return (session?.data as { PaymentURL?: string } | undefined)?.PaymentURL
14}
15
16/**
17 * Т-Касса принимает оплату на собственной странице. Сессия, созданная оформлением
18 * заказа, хранит адрес, куда отправить покупателя, а заказ оформляется, когда он
19 * вернётся через `/api/payment-return`, либо по вебхуку, если тот придёт раньше.
20 */
21const TkassaPaymentButton = ({
22  cart,
23  notReady,
24  label,
25  cartUpdating,
26  "data-testid": dataTestId,
27}: PaymentProviderButtonProps) => {
28  const t = useTranslations("Errors")
29  const [submitting, setSubmitting] = useState(false)
30  const [errorMessage, setErrorMessage] = useState<string | null>(null)
31
32  const handlePayment = () => {
33    const url = paymentUrl(cart)
34
35    if (!url) {
36      setErrorMessage(t("paymentFailed"))
37      return
38    }
39
40    setSubmitting(true)
41    window.location.assign(url)
42  }
43
44  return (
45    <PaymentButtonShell
46      label={label}
47      onClick={handlePayment}
48      disabled={notReady}
49      loading={submitting || cartUpdating}
50      errorMessage={errorMessage}
51      errorTestId="tkassa-payment-error-message"
52      data-testid={dataTestId ?? "submit-order-button"}
53    />
54  )
55}
56
57export default TkassaPaymentButton

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

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

---

Импортируйте кнопку и isTkassa в 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  isTkassa,
6} from "@lib/constants"
7// ...
8import TkassaPaymentButton from "./providers/tkassa"
9
10// ...
11
12  switch (true) {
13    // ...
14    case isTkassa(activePaymentMethod):
15      return <TkassaPaymentButton {...providerProps} />
16    default:
17      // ...
18  }

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

---

После того как покупатель завершает оплату на странице Т-Касса, он перенаправляется обратно на витрину магазина. Т-Касса сообщает статус платежа и через это перенаправление, и через вебхук, поэтому общий 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 * странице и возвращает покупателя только с идентификатором корзины — Т-Касса
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 направьте возврат Т-Касса в redirectProviderReturn:

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

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

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

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

---

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

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

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

---

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