photoplaces/backend/docs/PAYMENT_INTEGRATION.md

Интеграция 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

{
  "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)