Т-Касса от Т-Банка для Medusa: приём платежей для РФ

Плагин интеграции подключает интернет-эквайринг Т-Банка к магазину на Medusa. Онлайн-чеки по 54-ФЗ, одно- и двухстадийная оплата, возвраты, отмены и все настройки подключения в Admin.

Плагин для интернет-эквайринга Т-Кассы от Т-Банка мы опубликовали ещё летом 2025 года, и с тех пор его установили в продакшене многие магазины на Medusa, среди них Solidno, Ktsport и White Dog. Покупатель платит на защищённой странице банка, чек по 54-ФЗ уходит вместе с платежом, а доступы, чеки и возвраты администратор магазина ведёт прямо в Medusa Admin.

Как это работает, смотрите в демо:

Пример магазина с Т-Кассой на DTC Starter от Gorgo

Магазин из демо-видео построен на готовом к продакшену Medusa DTC Starter от Gorgo. Бэкенд Medusa и витрина на Next.js в нём отлажены и доведены до состояния готового к запуску. Вам остаётся только задать общие настройки магазина и заполнить каталог товаров. В этом примере Т-Касса уже подключена, а его код находится в репозитории на GitHub. Запустите его локально и пройдите тот же путь на тестовом терминале.

Открыть пример интеграции на GitHub

Что такое Т-Касса

Т-Касса принимает онлайн-платежи для интернет-магазинов в России. Это сервис интернет-эквайринга от Т-Банка (ранее Тинькофф Банк), одного из крупнейших цифровых банков страны. Покупатели платят картами, через СБП, T-Pay, SberPay, Alfa Pay, Mir Pay и другими способами. Оплата проходит в рублях, а из-за границы принимаются только карты «Мир». Подробнее о сервисе рассказано на сайте Т-Банка.

Как платит покупатель

На странице оформления заказа Т-Касса стоит отдельной плиткой рядом с другими способами оплаты.

Плитка Т-Кассы на странице оформления заказа в Medusa DTC Starter

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

Платёжная страница Т-Банка с формой оплаты картой

После оплаты покупатель возвращается на страницу заказа, а статус платежа приходит в Medusa по вебхуку.

Оплаченный заказ выглядит в Admin как обычный платёж Medusa. Если нужен возврат, его можно запустить из меню.

Платёж Т-Кассы в заказе Medusa Admin и меню с действием возврата

Что умеет плагин

Чеки по 54-ФЗ – плагин сам составляет чек из корзины и отправляет его в Т-Кассу вместе с платежом. Поддерживаются ФФД 1.05 и 1.2, пять систем налогообложения и отдельные ставки НДС для товаров и доставки.
Оплата сразу или после подтверждения – деньги можно списывать в момент оплаты. А можно сначала только заблокировать сумму на карте покупателя и списать её, когда вы подтвердите платёж в Admin. Второй вариант подходит, если перед списанием нужно проверить наличие товара.
Возвраты и отмена – полный или частичный возврат вы оформляете прямо в Admin, без похода в личный кабинет банка. Чек на частичный возврат плагин составит сам. Если заказ отменён до списания, плагин снимет блокировку суммы на карте покупателя.
Несколько терминалов в одном магазине – каждый подключается отдельно, со своими доступами и настройками. Это пригодится, если магазин продаёт от нескольких юрлиц в разных регионах или в разных каналах продаж, например в интернет-магазине и через POS-терминал.
Защита от поддельных уведомлений – Т-Касса сообщает магазину о каждой смене статуса платежа. Плагин проверяет подпись уведомления, поэтому подделка не отметит заказ оплаченным.
Стабильная работа – больше 70 автотестов покрывают около 85% кода. Они следят, чтобы API Т-Кассы не изменился незаметно и плагин работал с новыми версиями Medusa. Если тесты находят проблему, Gorgo выпускает обновление с исправлением. Как это устроено, мы рассказывали отдельно.

Настройка в Admin

Т-Касса настраивается через Модуль интеграций на странице Настройки → Интеграции → Т-Касса. Значения хранятся в базе данных, пароль шифруется, а сохранённые изменения плагин применяет со следующей операции, без перезапуска и повторного развёртывания магазина.

Что такое Модуль интеграций

Модуль интеграций хранит настройки плагинов в базе данных, поэтому их можно менять в Medusa Admin без повторного развёртывания магазина. Он строит страницу настроек по описанию параметров, которое даёт любой плагин или модуль, шифрует секреты, следит, чтобы обязательные поля были заполнены, и проверяет соединение с внешним сервисом. Через него уже настраиваются Т-Касса, ЮKassa, Robokassa, ApiShip, 1С и другие плагины от сообщества разработчиков на Medusa.

Подробнее о Модуле интеграций

Страница настроек Т-Кассы в Medusa Admin

Поля чека появляются, только когда отправка чеков включена.

Как установить

Понадобятся Medusa 2.17.2 или новее, Node.js 20 или новее и терминал интернет-эквайринга в Т-Бизнесе.

Шаг 1. Установите плагин Т-Кассы и Модуль интеграций

npm install @gorgo/medusa-integration @gorgo/medusa-payment-tkassa

Шаг 2. Зарегистрируйте плагины и провайдеры в

medusa-config.ts
1const TKASSA_INTEGRATION_ID = "tkassa-1"
2
3module.exports = defineConfig({
plugins: [
  {
    resolve: "@gorgo/medusa-integration",
    options: {
      encryptionKey: process.env.INTEGRATION_ENCRYPTION_KEY,
      providers: [
        {
          resolve: "@gorgo/medusa-payment-tkassa/providers/integration-tkassa",
          id: TKASSA_INTEGRATION_ID,
          options: {},
        },
      ],
    },
  },
  {
    resolve: "@gorgo/medusa-payment-tkassa",
    options: {},
  },
  // ...
],
modules: [
  {
    resolve: "@medusajs/medusa/payment",
    options: {
      providers: [
        {
          resolve: "@gorgo/medusa-payment-tkassa/providers/payment-tkassa",
          id: "tkassa",
          options: {
            id: TKASSA_INTEGRATION_ID,
          },
        },
      ],
    },
  },
  // ...
],
41})

Как провайдер находит свои настройки

Константа связывает две записи. По ней платёжный провайдер находит свой инстанс интеграции и получает его параметры.

Шаг 3. Задайте ключ шифрования

Ключ, которым Модуль интеграций шифрует пароль терминала, добавьте в бэкенда Medusa:

.env

INTEGRATION_ENCRYPTION_KEY=supersecret

Задайте ключ один раз и не меняйте его, иначе модуль не сможет расшифровать сохранённые секреты.

Шаг 4. Заполните настройки в Admin

Шаг 5. Подключите уведомления

В личном кабинете Т-Бизнеса откройте настройки терминала, выберите отправку уведомлений по протоколу HTTP и укажите адрес вебхука:

https://<домен-medusa>/hooks/payment/tkassa_tkassa

Установка и настройка подробно описаны в документации. Если витрина собрана на DTC-стартере, файлы, которые нужно в неё добавить, перечислены в руководстве по интеграции с витриной.

Что дальше

Интеграция с Т-Касса - это один из плагинов, которые мы выпускаем для Medusa. В нашем каталоге уже есть платежи через ЮKassa и Robokassa, доставка через ApiShip и обмен данными с 1С. Дальше выйдут новые платёжные, логистические, ERP, CRM и другие интеграции. Все они будут соблюдать наши стандарты качества и ежедневно проходить тестирование на совместимость с последними версиями Medusa и API сервисов. Как устроены эти тесты, мы рассказали в этой статье.

Новости о релизах публикуем в Telegram-канале Medusa.js Новости.

Поддержка и сообщество Medusa

Задавайте вопросы и обсуждайте Medusa в Telegram-сообществе, пишите о проблемах с плагином в чат поддержки Gorgo или открывайте Issues и Pull Requests на GitHub.