ospab.host/PAYMENT_MIGRATION.md

Миграция оплаты: DePay → FreeKassa

✅ Выполненные изменения

Backend

1. Создан новый модуль FreeKassa (backend/src/modules/payment/freekassa.routes.ts)

   • ✅ Endpoint уведомлений: GET /payment/freekassa/notification
   • ✅ Успешная оплата: GET /payment/freekassa/sucess
   • ✅ Неудачная оплата: GET /payment/freekassa/failure
   • ✅ Создание платежа: POST /payment/freekassa/create-payment
   • ✅ История платежей: GET /payment/freekassa/history
   • ✅ IP whitelist проверка (4 IP FreeKassa)
   • ✅ MD5 подпись для формы и уведомлений

2. Обновлен main router (backend/src/index.ts)

   • ✅ Заменен импорт: depayRoutes → freekassaRoutes
   • ✅ Изменен маршрут: /payment/depay → /payment

3. Обновлен .env (backend/.env)

   • ✅ Удалены переменные DePay: DEPAY_PUBLIC_KEY, DEPAY_FALLBACK_RATE
   • ✅ Добавлены переменные FreeKassa (требуют заполнения):

     FK_MERCHANT_ID=YOUR_MERCHANT_ID
     FK_SECRET_WORD_1=YOUR_SECRET_WORD_1
     FK_SECRET_WORD_2=YOUR_SECRET_WORD_2
     

4. Удален старый модуль DePay

   • ✅ Удален файл: backend/src/modules/payment/depay.routes.ts

5. Обновлена схема Prisma (backend/prisma/schema.prisma)

   • ✅ Удалено поле checkId из модели Notification
   • ⚠️ Требуется миграция БД (см. раздел "Развертывание")

6. Очищены ссылки на систему чеков

   • ✅ Удалено событие check:status из WebSocket events
   • ✅ Удалено поле checkId из notification controller
   • ✅ Удален модуль backend/src/modules/check/

Frontend

1. Переписан компонент оплаты (frontend/src/pages/dashboard/billing.tsx)

   • ✅ Удален DePay виджет
   • ✅ Добавлена форма для редиректа на FreeKassa
   • ✅ Динамическое создание формы с подписью
   • ✅ Открытие оплаты в новой вкладке

2. Обновлен package.json (frontend/package.json)

   • ✅ Удалена зависимость: @depay/widgets

3. Обновлен .env (frontend/.env)

   • ✅ Удалена переменная: VITE_DEPAY_INTEGRATION_ID

4. Удалена система проверки чеков

   • ✅ Удален файл: frontend/src/pages/dashboard/checkverification.tsx
   • ✅ Удален импорт и маршрут из mainpage.tsx
   • ✅ Удалена вкладка из панели администратора
   • ✅ Удалено событие check:status из WebSocket
   • ✅ Удалено поле checkId из типов уведомлений
   • ✅ Удалены переводы для чеков (en.ts, ru.ts)

---

🔧 Развертывание

1. Заполнить credentials FreeKassa

Откройте merchant.freekassa.com → Настройки → Магазины

В файле backend/.env замените:

FK_MERCHANT_ID=12345              # ID вашего магазина
FK_SECRET_WORD_1=your_secret_1    # Секретное слово 1 (для формы)
FK_SECRET_WORD_2=your_secret_2    # Секретное слово 2 (для уведомлений)

2. Настроить URL в FreeKassa панели

В настройках магазина на FreeKassa укажите:

• Result URL (уведомления): https://ospab.host/payment/freekassa/notification
• Success URL: https://ospab.host/payment/freekassa/sucess
• Failure URL: https://ospab.host/payment/freekassa/failure

⚠️ Важно: В скриншоте была опечатка /frekassa/ вместо /freekassa/. Убедитесь, что используете правильный путь!

3. Применить миграцию БД

После обновления schema.prisma нужно создать миграцию:

cd backend
npx prisma migrate dev --name remove_checkid_field

Или для production:

npx prisma migrate deploy

4. Переустановить зависимости

# Frontend
cd ospabhost/frontend
npm install

# Backend (если нужно)
cd ../backend
npm install

5. Пересобрать проекты

# Backend
cd backend
npm run build

# Frontend
cd ../frontend
npm run build

6. Перезапустить сервисы

# Если используется PM2
pm2 restart all

# Или через systemd
sudo systemctl restart ospab-backend
sudo systemctl restart ospab-frontend

---

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

1. Проверка создания платежа

curl -X POST https://api.ospab.host/payment/freekassa/create-payment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100}'

Ожидаемый ответ:

{
  "status": "success",
  "data": {
    "merchantId": "12345",
    "amount": 100,
    "orderId": "user123_1234567890",
    "signature": "abc123...",
    "currency": "RUB",
    "email": "user@example.com"
  }
}

2. Проверка уведомлений (webhook)

FreeKassa отправит GET запрос на /payment/freekassa/notification с параметрами:

• MERCHANT_ID - ID магазина
• AMOUNT - сумма платежа
• intid - ID транзакции FreeKassa
• MERCHANT_ORDER_ID - ваш order ID
• SIGN - MD5 подпись

Backend проверит:

1. ✅ IP адрес отправителя (whitelist)
2. ✅ MD5 подпись (через SECRET_WORD_2)
3. ✅ Уникальность платежа (не был обработан ранее)
4. ✅ Создаст запись в CryptoPayment
5. ✅ Увеличит баланс пользователя
6. ✅ Создаст транзакцию
7. ✅ Отправит уведомление
8. ✅ Вернет "YES"

3. Ручное тестирование

1. Войдите в личный кабинет
2. Перейдите в раздел "Billing"
3. Введите сумму (минимум 50 ₽)
4. Нажмите "Пополнить"
5. Откроется форма FreeKassa в новой вкладке
6. Выберите способ оплаты и оплатите
7. После оплаты FreeKassa отправит уведомление на backend
8. Баланс должен автоматически обновиться

---

⚠️ Важные замечания

Безопасность

1. IP Whitelist: Backend проверяет, что уведомления приходят только с IP FreeKassa:

   • 168.119.157.136
   • 168.119.60.227
   • 178.154.197.79
   • 51.250.54.238

2. MD5 подпись: Все уведомления проверяются на валидность подписи

3. Идемпотентность: Повторная обработка одного платежа блокируется

Отличия от DePay

Параметр	DePay	FreeKassa
Тип интеграции	Виджет (JavaScript)	Форма (POST redirect)
Валюта	Криптовалюта	RUB
Открытие	Модальное окно	Новая вкладка
Callback	WebSocket	GET webhook
Подпись	RSA	MD5

База данных

Используется существующая таблица CryptoPayment:

• blockchain = 'freekassa'
• token = 'RUB'
• status = 'completed'

---

📝 Удаленные функции

Система проверки чеков операторами

✅ Полностью удалена:

• Backend модуль /modules/check/
• Frontend страница checkverification.tsx
• Маршруты и импорты в mainpage
• WebSocket события check:status
• Поле checkId в уведомлениях
• Переводы для чеков
• Вкладка в админ-панели

---

🔍 Логи для отладки

Backend логирует все этапы обработки платежа:

# Посмотреть логи PM2
pm2 logs ospab-backend --lines 100

# Grep для FreeKassa
pm2 logs | grep FreeKassa

Ключевые логи:

• [FreeKassa] Notification received - получено уведомление
• [FreeKassa] IP check failed - неверный IP
• [FreeKassa] Invalid signature - неверная подпись
• [FreeKassa] Payment already exists - дубликат
• [FreeKassa] Payment processed successfully - успешно обработано

---

📞 Поддержка

Если возникли проблемы:

1. Проверьте логи backend: pm2 logs ospab-backend
2. Проверьте настройки FreeKassa (URL, секретные слова)
3. Убедитесь, что миграция БД применена
4. Проверьте, что переменные окружения заполнены

Документация FreeKassa: wiki.freekassa.com