T-Kassa Payment Provider

A comprehensive T-Kassa (Tinkoff) payment integration plugin for Medusa, enabling Russian merchants to accept online payments with full compliance to Russian regulations.

Overview

This plugin provides seamless integration with T-Kassa (formerly Tinkoff Kassa), one of Russia’s leading payment systems. It includes support for online receipt generation compliant with Russian Federal Law No. 54 (54-ФЗ), making it ideal for businesses operating in the Russian market.

Features

• T-Kassa Payment Integration - Full integration with Tinkoff’s T-Kassa payment gateway
• Online Receipt Generation - Compliant with Russian Federal Law No. 54 (54-ФЗ)
• Flexible Payment Flows:
  • Single-stage payments (immediate debit/autocapture)
  • Two-stage payments (authorization/hold and capture)
• Webhook Support - Real-time payment status notifications
• Refund Management - Full refund and order cancellation functionality
• Security - Webhook signature verification for secure transactions
• Detailed Logging - Comprehensive logging for all payment operations
• Test Mode - Payment simulation for development and testing
• MedusaJS v2 Compatible - Built for Medusa v2.7.0 and later

Requirements

• MedusaJS v2.7.0 or higher
• Node.js v20 or later
• T-Business account with active T-Kassa acquiring services
• Terminal ID and password from T-Kassa

Installation

Install the plugin using npm:

npm install @gorgo/medusa-payment-tkassa

Configuration

Environment Variables

Add your T-Kassa credentials to your .env file:

TKASSA_TERMINAL_ID=your_terminal_id
TKASSA_PASSWORD=your_terminal_password
TKASSA_TEST_MODE=false

Plugin Configuration

Add the plugin to your medusa-config.js:

const plugins = [
  // ... other plugins
  {
    resolve: "@gorgo/medusa-payment-tkassa",
    options: {
      terminal_id: process.env.TKASSA_TERMINAL_ID,
      password: process.env.TKASSA_PASSWORD,
      test_mode: process.env.TKASSA_TEST_MODE === "true",
      // Receipt generation settings for 54-ФЗ compliance
      receipt: {
        sno: "osn", // Tax system
        taxation: "osn", // Taxation type
        // Additional receipt settings
      },
    },
  },
]

Getting Started with T-Kassa

1. Open T-Business Account

1. Visit t-business.tinkoff.ru
2. Register for a business account
3. Complete business verification

2. Activate T-Kassa

1. Log into T-Business
2. Navigate to T-Kassa section
3. Apply for acquiring services
4. Wait for approval and activation

3. Get Credentials

Once approved, obtain:

• Terminal ID
• Terminal password
• Webhook secret (for verification)

Usage

Single-Stage Payments (Autocapture)

Single-stage payments automatically capture funds when the customer completes payment:

1. Customer initiates checkout
2. Payment is processed through T-Kassa
3. Funds are automatically debited
4. Webhook notification updates order status
5. Receipt is automatically generated

Two-Stage Payments (Authorization & Capture)

Two-stage payments allow you to authorize first and capture later:

1. Customer initiates checkout
2. Payment amount is authorized (held on customer’s card)
3. Merchant manually confirms capture when ready to fulfill
4. Funds are debited from customer’s account
5. Receipt is generated upon capture

Refunds

The plugin supports full refund functionality:

• Process refunds through the Medusa admin
• Automatic refund processing through T-Kassa
• Receipt generation for refunded transactions
• Partial and full refund support

Webhooks

Configure webhooks in your T-Kassa account to receive real-time payment status updates:

https://your-domain.com/hooks/payment/tkassa

The plugin automatically:

• Receives webhook notifications
• Verifies webhook signatures
• Updates order payment status
• Generates transaction logs

Payment Flow

Customer Journey

1. Product Selection - Customer adds items to cart
2. Checkout - Customer proceeds to checkout
3. Payment Method - Customer selects T-Kassa payment
4. Redirect - Customer is redirected to T-Kassa payment page
5. Payment - Customer completes payment
6. Return - Customer is redirected back to store
7. Confirmation - Order is confirmed with receipt

Admin Operations

1. Monitor Payments - View payment status in admin
2. Capture Funds - Capture authorized payments (two-stage)
3. Process Refunds - Issue refunds when needed
4. View Receipts - Access generated receipts
5. Transaction Logs - Review detailed payment logs

Receipt Generation (54-ФЗ Compliance)

The plugin automatically generates online receipts compliant with Russian Federal Law No. 54. Configure receipt settings based on your business:

Tax Systems (SNO)

• osn - General taxation system
• usn_income - Simplified taxation (income)
• usn_income_outcome - Simplified taxation (income minus expenses)
• envd - Single tax on imputed income
• esn - Unified agricultural tax
• patent - Patent taxation system

Taxation Types

Configure taxation for products:

• osn - General
• usn_income - Simplified income
• usn_income_outcome - Simplified income-outcome
• envd - Imputed income
• esn - Agricultural
• patent - Patent

Receipt Configuration

{
  resolve: "@gorgo/medusa-payment-tkassa",
  options: {
    // ... other options
    receipt: {
      sno: "osn", // Your tax system
      taxation: "osn", // Default taxation
      email: "receipts@yourstore.ru", // Receipt email
      phone: "+79001234567", // Receipt phone
    },
  },
}

Test Mode

Enable test mode for development:

{
  resolve: "@gorgo/medusa-payment-tkassa",
  options: {
    test_mode: true,
    // ... other options
  },
}

In test mode:

• Use test credentials from T-Kassa
• Simulate various payment scenarios
• Test webhook handling
• Verify receipt generation
• No real money is processed

Security

Webhook Verification

The plugin automatically verifies webhook signatures to ensure:

• Webhooks are from T-Kassa
• Data hasn’t been tampered with
• Replay attacks are prevented

Secure Storage

Sensitive data handling:

• Credentials stored in environment variables
• No plain text passwords in code
• Encrypted communication with T-Kassa
• Secure token handling

Logging

Comprehensive transaction logging includes:

• Payment initiation
• Authorization results
• Capture operations
• Refund transactions
• Webhook events
• Error messages
• Receipt generation

Access logs through:

• Medusa admin panel
• Server logs
• T-Business dashboard

Troubleshooting

Payment Failures

Insufficient Funds:

• Customer’s card has insufficient balance
• Suggest alternative payment method

Card Declined:

• Card blocked by bank
• Customer should contact their bank

3DS Authentication Failed:

• Customer failed 3D Secure verification
• Retry with correct credentials

Webhook Issues

Webhook Not Received:

• Verify webhook URL in T-Kassa settings
• Check firewall rules
• Review server logs

Signature Verification Failed:

• Verify webhook secret is correct
• Check for configuration mismatches

Links

• Documentation
• T-Business
• T-Kassa Documentation