# Интеграция CloudPayments

## Общие принципы
- Для РФ — CloudPayments (агрегатор с поддержкой карт, СБП, ЮMoney, SberPay)
- Для международных пользователей — Stripe (на будущее)
- Выбор провайдера на основе `user.country` или IP

---

## CloudPayments: основные возможности

| Возможность | Поддержка |
|-------------|-----------|
| Приём карт Visa/Mastercard/Мир | ✅ |
| СБП (Система быстрых платежей) | ✅ |
| ЮMoney, SberPay, Tinkoff Pay | ✅ |
| Регулярные платежи (подписки) | ✅ |
| Вебхуки | ✅ |
| Тестовый режим | ✅ |
| Хостинг виджета | CloudPayments арендует страницу приёма, или виджет на своей странице |
| Чеки (54-ФЗ) | ✅ через онлайн-кассу |

---

## Способы оплаты

### 1. Разовый платёж (донат, разовая услуга)
- CloudPayments Widget (iframe на фронтенде)
- PayForm (страница на стороне CP)
- API Cryptogram (для бесшовного опыта)

### 2. Регулярные подписки (аренда студии, премиум)
- CloudPayments API: создание подписки через токен карты
- Первый платёж — как разовый, сохраняем `Token` и `AccountId`
- Далее — рекуррент по расписанию

---

## Поток платежа (через виджет)

```
1. Фронтенд запрашивает сумму и описание
2. Бэкенд создаёт платёж в БД (status: pending)
3. Фронтенд открывает CloudPayments Widget:
   - publicId, amount, currency, invoiceId (наш ID), description, accountId (user ID)
4. Пользователь вводит данные карты
5. CloudPayments отправляет вебхук на /webhooks/cloudpayments
6. Бэкенд:
   - Проверяет подпись (HMAC-SHA256)
   - Обновляет статус платежа в БД
   - Начисляет услугу / активирует подписку
7. Фронтенд опрашивает статус и показывает результат
```

---

## API CloudPayments

### Настройки
- `PublicId` — публичный ID для виджета
- `ApiSecret` — секретный ключ для API (на бэкенде)
- Тестовые карты: `4111111111111112`, `5555555555554444`

### Вебхук CloudPayments

**URL:** `POST /api/v1/webhooks/cloudpayments`

```json
{
  "TransactionId": 12345,
  "Amount": 150000,
  "Currency": "RUB",
  "DateTime": "2024-01-15T10:30:00",
  "InvoiceId": "our-payment-uuid",
  "AccountId": "our-user-uuid",
  "Email": "user@example.com",
  "SubscriptionId": null,
  "Token": "token-for-recurring",
  "Name": "SAIPAY",
  "CardType": 0,
  "IpCountry": "RU",
  "IpCity": "Moscow",
  "IpRegion": "Moscow",
  "Data": {}
}
```

**Проверка подписи (HMAC-SHA256):**
- Секрет: `ApiSecret`
- Данные: тело запроса в формате JSON
- Заголовок `Content-HMAC`

---

## Структура тарифов (MVP)

### Бесплатно
- Размещение мест (для Заказчиков): бесплатно
- Просмотр карты и карточек: бесплатно
- Размещение услуг (для Исполнителей): 1 услуга бесплатно

### Платно
| Тариф | Цена | Кому | Описание |
|-------|------|------|----------|
| Размещение студии | ~1000р/мес | Арендодателям | Студия видна на карте |
| Премиум-исполнитель | ~500р/мес | Исполнителям | До 10 услуг, приоритет в выдаче |
| Донат | Любая сумма | Всем | Поддержка проекта |
| Продвижение места | ~300р/нед | Заказчикам | Место в топе выдачи |

---

## План реализации (MVP без платежей)

1. **Этап 1 (MVP)**: запуск без платежей — все функции бесплатно
2. **Этап 2**: CloudPayments — разовые донаты
3. **Этап 3**: Подписки на размещение студий
4. **Этап 4**: Продвижение мест и услуг
5. **Будущее**: Stripe для международных пользователей

---

## Обработка ошибок

| Ситуация | Действие |
|----------|----------|
| Платеж отклонён банком | Показать пользователю "Попробуйте другую карту" |
| Вебхук с неверной подписью | Вернуть 401, не обновлять статус |
| Платеж пришёл с неизвестным InvoiceId | Вернуть 200, залогировать |
| Повторный вебхук (дубль) | Игнорировать, если статус уже succeeded |

## Требования к бэкенду

- Пакеты Go: `github.com/cloudpayments/sdk-go`
- Эндпоинт вебхука: без аутентификации (проверка HMAC)
- Таблица `payments` и `subscriptions` в БД (см. DB_SCHEMA.md)