T-Kassa by T-Bank for Medusa: Accept Payments in Russia

The integration plugin connects T-Bank's internet acquiring to a Medusa store. Online receipts under 54-FZ, one-step and two-step payments, refunds, cancellations and every connection setting in the Admin.

We published the plugin for T-Kassa, T-Bank's internet acquiring service, back in summer 2025, and since then many Medusa stores have put it into production, among them Solidno, Ktsport and White Dog. The buyer pays on the bank's secure page, a receipt under Russia's fiscal law 54-FZ goes out with the payment, and the store admin manages credentials, receipts and refunds right in the Medusa Admin.

See how it works in the demo:

A Store with T-Kassa on Gorgo's DTC Starter

The store in the demo video is built on Gorgo's production-ready Medusa DTC Starter. Its Medusa backend and Next.js storefront are debugged and ready to launch, so all that's left is to set the general store settings and fill in the product catalog. In this example T-Kassa is already connected, and its code is in the GitHub repository. Run it locally and walk the same path against a test terminal.

Open the integration example on GitHub

What Is T-Kassa

T-Kassa accepts online payments for online stores in Russia. It is the internet acquiring service of T-Bank (formerly Tinkoff Bank), one of the country's largest digital banks. Buyers pay by card, through SBP, T-Pay, SberPay, Alfa Pay, Mir Pay and other methods. Payments are made in roubles, and from abroad only Mir cards are accepted. More about the service is on T-Bank's website.

How the Buyer Pays

At checkout, T-Kassa appears as its own tile next to the other payment methods.

The T-Kassa tile at checkout in Medusa DTC Starter

The Pay button takes the buyer to T-Bank's payment page. Card details are entered there and never reach the store. Which payment methods the page offers is up to the terminal settings in the T-Business dashboard.

T-Bank's payment page with the card form

Once the payment goes through, the buyer lands back on the order page, and the payment status reaches Medusa through a webhook.

A paid order shows up in the Admin as a regular Medusa payment. If a refund is needed, it can be started from the payment's menu.

A T-Kassa payment on a Medusa Admin order, with the refund action in its menu

What the Plugin Does

Receipts under 54-FZ – the plugin builds the receipt from the cart itself and sends it to T-Kassa along with the payment. It supports fiscal data formats 1.05 and 1.2, five tax systems and separate VAT rates for products and shipping.
Charge now or after confirmation – the money can be debited at the moment of payment. Or the amount can first be held on the buyer's card and debited once you confirm the payment in the Admin. The second option suits a store that checks stock before charging.
Refunds and cancellation – you issue a full or partial refund right in the Admin, without going to the bank's dashboard. The plugin builds the receipt for a partial refund itself. If an order is canceled before the charge, the plugin releases the hold on the buyer's card.
Several terminals in one store – each one connects separately, with its own credentials and settings. This helps when a store sells on behalf of several legal entities in different regions, or across different sales channels, such as the online store and a POS terminal.
Protection against forged notifications – T-Kassa notifies the store of every payment status change. The plugin checks each notification's signature, so a forged one can't mark an order as paid.
Stable operation – more than 70 automated tests cover about 85% of the code. They catch any unannounced change in the T-Kassa API and check that the plugin works with new Medusa versions. If the tests find a problem, Gorgo releases a fix. We wrote separately about how this works.

Settings in the Admin

T-Kassa is configured through the Integration Module on the Settings → Integrations → T-Kassa page. Values are stored in the database, the password is encrypted, and the plugin picks up saved changes on its next operation, with no restart and no redeployment of the store.

What Is the Integration Module

The Integration Module stores plugin settings in the database, so they can be changed in the Medusa Admin without redeploying the store. It builds the settings page from the description of options that any plugin or module provides, encrypts secrets, makes sure required fields are filled in and checks the connection to the external service. T-Kassa, YooKassa, Robokassa, ApiShip, 1C and other plugins from the Medusa developer community are already configured through it.

More about the Integration Module

The T-Kassa settings page in Medusa Admin

The receipt fields appear only when sending receipts is on.

How to Install

You need Medusa 2.17.2 or later, Node.js 20 or later, and an internet acquiring terminal in T-Business.

Step 1. Install the T-Kassa Plugin and the Integration Module

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

Step 2. Register the Plugins and Providers in

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})

How the Provider Finds Its Settings

The constant ties the two entries together. The payment provider uses it to find its integration instance and get that instance's options.

Step 3. Set the Encryption Key

Add the key the Integration Module uses to encrypt the terminal password to the of the Medusa backend:

.env

INTEGRATION_ENCRYPTION_KEY=supersecret

Set the key once and don't change it, or the module can no longer decrypt the stored secrets.

Step 4. Fill In the Settings in the Admin

Open Settings → Integrations and choose T-Kassa.
Enter the terminal key and password in the Credentials section.
Turn on receipts and set their options in the Receipt section, if you need them.
Enable the integration.
Add T-Kassa to the region's payment providers under Settings → Regions.

T-Kassa in the Settings → Integrations list

Step 5. Connect the Notifications

In the T-Business dashboard, open the terminal settings, choose to send notifications over HTTP, and enter the webhook URL:

https://<your-medusa-domain>/hooks/payment/tkassa_tkassa

Installation and setup are covered in detail in the documentation. If your storefront is built on the DTC starter, the files to add to it are listed in the storefront integration guide.

What's Next

The T-Kassa integration is one of the plugins we build for Medusa. Our catalog already has YooKassa and Robokassa payments, ApiShip shipping and data exchange with 1C. More payment, shipping, ERP, CRM and other integrations are on the way. All of them will meet our quality standards and be tested daily for compatibility with the latest Medusa versions and provider APIs. We explained how these tests work in this post.

We announce releases in the Medusa.js News Telegram channel.

Support and the Medusa Community

Ask questions and discuss Medusa in the Telegram community, report plugin issues in the Gorgo support chat, or open Issues and Pull Requests on GitHub.