# Platega.io — настройка платёжного провайдера

Источник: <https://docs.platega.io/>

Platega используется как единый шлюз, за которым скрыты несколько методов
оплаты: **СБП (QR)**, **ЕРИП**, **карточный эквайринг**, **международная
оплата** и **криптовалюта**. Плательщик выбирает метод сам на странице
Platega — мы используем endpoint `POST /v2/transaction/process`.

## 1. Получение креденшелов

1. Войдите в ЛК Platega → **Настройки**.
2. Скопируйте:
   - **MerchantId** (UUID формата `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) —
     будет передан в заголовке `X-MerchantId`.
   - **API ключ (Secret)** — будет передан в заголовке `X-Secret`.

## 2. Настройка в админке LinkSnap

Админка → таб **Platega**:

1. Вставьте **Merchant UUID**.
2. Вставьте **API Secret** (шифруется через `BILLING_SETTINGS_ENCRYPTION_KEY`).
3. Убедитесь, что **Fiat валюта** = `USD`.
4. (опционально) задайте **Срок жизни инвойса** — используется как fallback,
   реальное время жизни задаёт сама Platega (обычно 15 минут).
5. Нажмите **«Проверить»** — выполняется `GET /balances`. Успех обновляет
   `lastCheckedAt`.
6. Включите переключатель **«Приём платежей Platega»** и **Сохранить все**.

## 3. Подключение Callback URL

У Platega callback URL задаётся **глобально в ЛК**, а не в теле запроса
создания платежа.

1. В админке LinkSnap скопируйте поле **Webhook URL** из таба Platega. Формат:
   `https://<host>/api/billing/providers/platega/webhook/<webhookPathSecret>`
2. В ЛК Platega → **Настройки → Callback URLs** → вставьте этот URL.
3. Убедитесь, что домен отдаёт валидный SSL-сертификат (самоподписанные
   недопустимы, приватные IP и localhost тоже запрещены — требование Platega).

## 4. Проверка работы

1. Нажмите **«Проверить»** в админке — должно показать «Подключение Platega
   успешно проверено».
2. Сделайте тестовую оплату через тариф (Pricing → выбрать «Platega»).
3. Оплатите инвойс; проверьте, что в админке:
   - `Последний webhook` — обновился;
   - в таблице инвойсов статус стал `PAID`;
   - тариф пользователя активировался (`BillingEntitlement` → `ACTIVE`).

## 5. Особенности интеграции и безопасность

- **Нет HMAC-подписи у webhook.** Platega присылает только заголовки
  `X-MerchantId` и `X-Secret`. Мы сверяем их constant-time со значениями,
  хранящимися зашифрованными в `PaymentProviderConfig`. Дополнительно URL
  содержит 256-битный секрет `webhookPathSecret` из cuid — без него webhook
  вернёт `200 { ok: true }` без раскрытия подробностей.
- **Связь invoice ↔ Platega-транзакция** идёт через поле `payload`:
  мы кладём туда `{"invoiceId":"<BillingInvoice.id>"}`. Fallback —
  по `transactionId → BillingInvoice.externalInvoiceHash`.
- **Статусы**: `PENDING`, `CANCELED`, `CONFIRMED`, `CHARGEBACKED`. Активацию
  entitlement делает только `CONFIRMED`. Остальные — `IGNORED`-событие в
  `BillingWebhookEvent` без изменения биллинга.
- **Ретраи**: Platega делает до 3 повторных попыток с интервалом 5 минут при
  таймауте/ошибке; дедуп у нас обеспечивает `BillingWebhookEvent.dedupeKey`.

## 6. Env-переменные

Никаких новых обязательных env не требуется. Платёжные ключи хранятся в БД
в зашифрованном виде. Опционально можно переопределить базовый URL API:

- `PLATEGA_API_BASE_URL` — по умолчанию `https://app.platega.io/`.

## 7. Откат

Для отключения провайдера без удаления конфига достаточно выключить
переключатель **«Приём платежей Platega»** в админке. Пользователь не увидит
Platega среди способов оплаты (`/api/billing/payment-methods` вернёт
`{ id: "platega", enabled: false }`).