Tochka

Платежи Точка Банка для Medusa

Плагин Medusa для приёма платежей через Точка Банк.
Read README in English ↗

Возможности

• 🔗 Бесшовная интеграция с платёжной системой Точка Банк
• 🧾 Формирование онлайн-чеков в соответствии с 54-ФЗ (российские фискальные требования)
• 1️⃣ Одностадийные (автосписание) и 2️⃣ двухстадийные (авторизация/холдирование) сценарии оплаты
• 🔄 Полные и частичные возвраты
• 🔔 Вебхук-уведомления о статусах платежей в реальном времени
• 🛡 JWT-верификация вебхуков с использованием JWK публичных ключей для повышенной безопасности
• 💳 Множественные способы оплаты - банковские карты, СБП (Система Быстрых Платежей) и другие
• 🔍 Подробное логирование для отладки и мониторинга
• 🏦 Эквайринговые операции - полная интеграция с платформой интернет-эквайринга Точка Банк

Требования

• Medusa v2.7.0 или выше
• Node.js v20 или выше
• Аккаунт Точка Банк с подключенным интернет-эквайрингом
• JWT токен и client ID от Точка Банк
• Публичный ключ webhook от Точка Банк (для верификации вебхуков)

Установка

1yarn add medusa-payment-tochka
2# или
3npm install medusa-payment-tochka

Конфигурация

Добавьте плагин в ваш medusa-config.ts:

1module.exports = defineConfig({
2    modules: [
3// ... другие модули
4        {
5            resolve: "@medusajs/medusa/payment",
6            options:
7                {
8                    providers: [
9                        {
10                            resolve: "medusa-payment-tochka/providers/payment-tochka",
11                            id: "tochka",
12                            options: {
13                                tochkaJwtToken: process.env.TOCHKA_JWT_TOKEN,
14                                clientId: process.env.TOCHKA_CLIENT_ID,
15                                webhookPublicKeyJson: process.env.TOCHKA_WEBHOOK_PUBLIC_KEY,
16                                tochkaApiVersion: "v1.0", // опционально, по умолчанию "v1.0"
17                                developerMode: process.env.NODE_ENV !== "production", // опционально, по умолчанию false
18                                preAuthorization: false, // опционально, включить двухстадийные платежи
19                                paymentPurpose: "Оплата заказа", // опционально, описание платежа по умолчанию
20                                withReceipt: true, // опционально, включить формирование чеков
21                                taxSystemCode: "usn_income", // обязательно если withReceipt = true
22                                taxItemDefault: "vat0", // обязательно если withReceipt = true
23                                taxShippingDefault: "vat0", // обязательно если withReceipt = true
24                            },
25                        }
26                    ]
27                }
28        }
29    ]
30})

Переменные окружения

Создайте файл .env со следующими переменными:

1# Обязательные
2TOCHKA_JWT_TOKEN=ваш_jwt_токен_от_точка_банк
3TOCHKA_CLIENT_ID=ваш_client_id_от_точка_банк
4TOCHKA_WEBHOOK_PUBLIC_KEY='{"kty":"RSA","e":"AQAB","n":"значение_n_вашего_публичного_ключа"}'
5
6# Опциональные
7TOCHKA_API_VERSION=v1.0
8TOCHKA_DEVELOPER_MODE=false

Поддержка API

Этот плагин обеспечивает комплексную поддержку API эквайринга Точка Банк:

Платёжные операции

• Создание платёжной операции - Генерация ссылок для оплаты
• Получение статуса платежа - Проверка статуса платёжной операции
• Подтверждение платежа - Завершение двухстадийных платежей
• Возврат платежа - Обработка полных или частичных возвратов
• Платежи с чеками - Формирование фискальных чеков в соответствии с российским 54-ФЗ

Поддержка вебхуков

• JWT-верификация - Безопасная валидация вебхуков с использованием JWK публичных ключей
• Обновления в реальном времени - Мгновенные уведомления о статусе платежей
• Маппинг статусов - Автоматическое преобразование в статусы платежей Medusa

Поддерживаемые способы оплаты

• Банковские карты (Visa, Mastercard, Мир)
• СБП (Система Быстрых Платежей)
• Рассрочка (Долями, Тинькофф)

Тестирование

1# Запуск тестов
2npm test
3
4# Запуск тестов в режиме наблюдения
5npm run test:watch

Разработка

1# Запуск в режиме разработки
2npm run dev
3
4# Сборка плагина
5npm run build

Лицензия

Распространяется на условиях лицензии MIT.

Поддержка

Если у вас возникли проблемы или вопросы по этому плагину, пожалуйста:

1. Проверьте GitHub Issues
2. Создайте новую проблему, если ваша ещё не зарегистрирована
3. Предоставьте подробную информацию о вашей настройке и проблеме, с которой вы столкнулись

Участие в разработке

Мы приветствуем участие в разработке! Пожалуйста, не стесняйтесь отправлять Pull Request.