Command Palette

Search for a command to run...

Getting Started with T-Kassa Payment

In this document, you’ll learn how to install and configure the T-Kassa payment provider for Medusa.

Requirements

  • Medusa v2.7.0 or later
  • Node.js v20 or later
  • A T-Business account with T-Kassa internet acquiring – sign in or create one

Installation

yarn add @gorgo/medusa-payment-tkassa
# or
npm install @gorgo/medusa-payment-tkassa

Configuration

Add the provider configuration in your file of the Medusa admin application:

# ...
module.exports = defineConfig({
  # ...
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "@gorgo/medusa-payment-tkassa/providers/payment-tkassa",
            id: "tkassa",
            options: {
              terminalKey: process.env.TKASSA_TERMINAL_KEY,
              password: process.env.TKASSA_PASSWORD,
              capture: true,
              useReceipt: true,
              ffdVersion: "1.05",
              taxation: "osn",
              taxItemDefault: "none",
              taxShippingDefault: "none"
            },
          }
        ]
      }
    }
  ]
})

Add environment variables with your shop identifier and secret from your T-Business account:

TKASSA_TERMINAL_KEY=123456789
TKASSA_PASSWORD=supersecret

Provider Options

OptionDescriptionRequiredDefault
Terminal key provided by T-Kassa (required for authentication)Yes-
Password for request signing (required for authentication)Yes-
Automatic payment capture:
- for one-step payment, passes to T-Kassa API
- for two-steps payment, passes payment		No
Enable receipt generation according to Russian fiscal data format (FFD)No
Fiscal data format version: or
Applicable only if = 		No-
Tax system type:
- : General
- : Simplified (income)
- : Simplified (income-expenses)
- : Agricultural
- : Patent
Applicable only if = 		No-
Default VAT rate for products:
- : No VAT
- : 0%
- : 5%
- : 7%
- : 10%
- : 20%
- : 5/105
- : 7/107
- : 10/110
- : 20/120
Applicable only if = 		No-
Default VAT rate for shipping, same options as
Applicable only if = 		No-

Webhook Setup

To properly handle payment notifications from T-Kassa, configure webhooks in your T-Business account as following:

  1. Navigate to → → Choose your shop → → Choose or Terminal → Click to open the setting window

  2. Choose to send Notifications

  3. Add a URL like:

    Change with your medusa store domain.

Warning! T-Kassa expects an response message to confirm successful webhook processing and to prevent duplicate notifications. Currently, Medusa does not natively support custom webhook response messages, but webhooks are still processed correctly without this. For more details, check out the related discussion.

OverviewStorefront Integration
Getting Started with T-Kassa Payment