---
title: "Інтеграція WayForPay"
description: "Повний посібник з інтеграції WayForPay для оновлення членства та генерації доходу"
locale: "uk"
---
# Інтеграція Платежів 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/uk/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 UAH
    currency: 'UAH',
    description: 'Оновлення Учасника Ring Platform',
    duration: '1 місяць'
  },
  [UserRole.confidential]: {
    amount: 999,        // ₴999 UAH  
    currency: 'UAH',
    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) для експертного керівництва по обробці платежів, найкращих практик безпеки та оптимізації доходу.