---
title: "Интеграция WayForPay"
description: "Полное руководство по интеграции WayForPay для обновления членства и генерации дохода"
locale: "ru"
---
# Интеграция Платежей WayForPay

> **Success**
> **Система Оплаты Членства** - Полная PCI-DSS совместимая платежная система для обновления ПОДПИСЧИК→УЧАСТНИК с автоматическим управлением ролями и обработкой вебхуков.

Ring Platform интегрирует платежный шлюз **WayForPay** для обеспечения безопасного обновления членства, автоматически повышая роль пользователя с ПОДПИСЧИК до УЧАСТНИК после успешной оплаты.

## Обзор

### Что такое WayForPay?

WayForPay — ведущий украинский платежный шлюз с поддержкой:
- 💳 Банковские карты (Visa, MasterCard)
- 📱 Цифровые кошельки (Apple Pay, Google Pay)
- 🏦 Украинские банки (Privat24, LiqPay)
- 📅 Рассрочки (PayParts, мгновенные рассрочки)
- 💱 Мультивалютная поддержка (UAH, USD, EUR)

### Архитектура Платежей

```mermaid
sequenceDiagram
    participant U as Пользователь
    participant P as Модальное окно
    participant S as Серверное действие
    participant W as WayForPay
    participant WH as Вебхук
    participant DB as База данных

    U->>P: Нажимает "Обновить до УЧАСТНИКА"
    P->>S: initiateMembershipPayment()
    S->>S: Генерирует HMAC-MD5 подпись
    S->>W: Создает платежную сессию
    W-->>S: Возвращает URL платежа
    S-->>P: Возвращает URL платежа
    P->>W: Перенаправляет пользователя на WayForPay
    U->>W: Вводит платежные данные (₴299 UAH)
    W->>W: Обрабатывает платеж
    W->>WH: POST /api/payments/wayforpay/webhook
    WH->>WH: Проверяет HMAC подпись
    WH->>DB: upgradeUserRole()
    DB->>DB: ПОДПИСЧИК → УЧАСТНИК
    WH-->>W: Возвращает подписанное подтверждение
    W->>U: Перенаправляет на страницу успеха
    U->>P: Просматривает подтверждение
```

## Настройка

### Переменные Окружения

> **Warning**
> **Критично для безопасности**: Никогда не раскрывайте `WAYFORPAY_SECRET_KEY` в клиентском коде. Вся генерация подписей должна происходить на сервере.

Добавьте в ваш `.env.local`:

Интеграция платежей WayForPay URL приложения (для обратных вызовов)

{`WAYFORPAY_MERCHANT_ACCOUNT=ваш_аккаунт_wayforpay
WAYFORPAY_SECRET_KEY=ваш_секретный_ключ
WAYFORPAY_DOMAIN=ваш-домен.com

NEXTAUTH_URL=https://ваш-домен.com`}

### Получение Учетных Данных

  
**Создайте аккаунт WayForPay**

    1. Посетите [wayforpay.com](https://wayforpay.com/ru/account/api)
    2. Зарегистрируйтесь как мерчант
    3. Завершите KYC верификацию
    4. Перейдите в Настройки → API
    5. Скопируйте аккаунт мерчанта и секретный ключ

  
**Настройте URL вебхука**

    В панели WayForPay:
    - URL сервиса: `https://ваш-домен.com/api/payments/wayforpay/webhook`
    - Должен быть HTTPS
    - Должен быть публично доступен

  
**Тестирование с песочницей**

    Используйте тестовые учетные данные для разработки:
    
{`WAYFORPAY_SECRET_KEY=test_secret_key`}

## Реализация

### Уровень Сервиса

Сервис WayForPay (`lib/payments/wayforpay-service.ts`) предоставляет три основные функции:

#### 1. Инициация Платежа

{`import { initiatePayment, MEMBERSHIP_PRICES } from '@/lib/payments/wayforpay-service'
const paymentRequest = {
  userId: session.user.id,
  userEmail: session.user.email,
  targetRole: UserRole.member,
  returnUrl: 'https://ваш-домен.com/membership/success',
  callbackUrl: 'https://ваш-домен.com/api/payments/wayforpay/webhook'
}

const response = await initiatePayment(paymentRequest)

if (response.success) {
  // Перенаправить пользователя на URL платежа
  window.location.href = response.paymentUrl
}`}

#### 2. Обработка Вебхука

{`import { verifyWebhookSignature, processSuccessfulPayment } from '@/lib/payments/wayforpay-service'
// В вашем обработчике маршрута вебхука
const payload = await request.json()

// КРИТИЧНО: Всегда проверяйте подпись
if (!verifyWebhookSignature(payload)) {
  return Response.json({ error: 'Неверная подпись' }, { status: 401 })
}

// Обработать платеж и обновить роль пользователя
const success = await processSuccessfulPayment(payload)`}

### Настройка Цен

Текущие цены членства:

{`[UserRole.member]: {
    amount: 299,        // 299 RUR
    currency: 'RUR',
    description: 'Обновление Участника Ring Platform',
    duration: '1 месяц'
  },
  [UserRole.confidential]: {
    amount: 999,        // 999 RUR
    currency: 'RUR',
    description: 'Конфиденциальное Членство Ring Platform',
    duration: '1 месяц'
  }
}`}

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

### Проверка HMAC-MD5 Подписи

> **Error**
> **Требование Безопасности**: Все вебхуки ДОЛЖНЫ проверять HMAC-MD5 подписи перед обработкой. Это предотвращает несанкционированные обновления ролей и платежное мошенничество.

**Генерация подписи**:

{`function generateSignature(data: Record<string, any>): string {
  // Объединить значения с разделителем точка с запятой
  const signatureString = Object.values(data).join(';')
  
  // Генерировать HMAC-MD5 хеш с секретным ключом
  return crypto
    .createHmac('md5', WAYFORPAY_SECRET_KEY)
    .update(signatureString)
    .digest('hex')
}`}

### Соответствие PCI-DSS

Ring Platform поддерживает соответствие PCI-DSS через:

✅ **Хостинг Платежной Страницы**: Данные карт не касаются вашего сервера  
✅ **Без Хранения Карт**: Никогда не храните полные номера карт или CVV  
✅ **Только HTTPS**: Вся коммуникация зашифрована  
✅ **Валидация Подписи**: Каждый вебхук проверен  
✅ **Аудит**: Полное логирование истории платежей  

## Система Обновления Ролей

При успешной оплате система автоматически:

1. **Проверяет** подпись вебхука
2. **Валидирует** статус транзакции
3. **Извлекает** ID пользователя из референса заказа
4. **Обновляет** роль пользователя в базе данных
5. **Записывает** метаданные платежа
6. **Логирует** событие обновления

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

### Тестовая Среда

> **Info**
> WayForPay предоставляет песочницу с тестовыми картами для интеграционного тестирования.

**Тестовые Учетные Данные**:

{`WAYFORPAY_SECRET_KEY=flk3409refn54t54t*FNJRET`}

**Тестовые Карты**:
```
Visa (Успех):       4111111111111111
Visa (Отклонено):   4000000000000002
MasterCard (Успех): 5555555555554444
```

## Контрольный Список Продакшена

  
**Перед Запуском**
    
    - [ ] Настроены учетные данные продакшена
    - [ ] URL вебхука установлен на HTTPS точку продакшена
    - [ ] Переменные окружения защищены
    - [ ] Проверка подписи протестирована
    - [ ] Платежный поток протестирован от начала до конца
    - [ ] Страницы успеха/неудачи проверены
    - [ ] Логирование полное
    - [ ] Обработка ошибок завершена

  
**День Запуска**
    
    - [ ] Мониторить первые транзакции внимательно
    - [ ] Проверить вебхуки получены и обработаны
    - [ ] Проверить обновления ролей успешны
    - [ ] Мониторить ошибки валидации подписи
    - [ ] Отслеживать уровень успеха платежей
    - [ ] Иметь команду поддержки готовой

---

## Следующие Шаги

> **Success**
> **Интеграция WayForPay завершена!** Теперь вы можете:

- ✅ Принимать обновления членства за ₴299 UAH
- ✅ Автоматически обновлять ПОДПИСЧИК→УЧАСТНИК
- ✅ Отслеживать историю платежей и аналитику
- ✅ Обрабатывать успех и неудачи корректно
- ✅ Генерировать доход от уровней членства

> **Info**
> **Нужна помощь с интеграцией платежей?** Консультируйтесь с [WayForPay Integrator Specialist](./AI-LEGIOX/legiox-truth-lens/wayforpay-integrator-skillset.json) (Legiox Agent #124) для экспертного руководства по обработке платежей, лучших практик безопасности и оптимизации дохода.