# Heleket Billing Setup Документ описывает запуск и поддержку оплаты подписок через Heleket в LinkSnap. ## 1) Подготовить ключ шифрования billing-настроек В окружении приложения должен быть задан: ```env BILLING_SETTINGS_ENCRYPTION_KEY="<64 hex chars>" ``` Требования: - ровно 64 hex-символа; - используется для AES-256-GCM шифрования `apiKey`, который хранится в `PaymentProviderConfig.apiTokenEncrypted`. Пример генерации: ```bash node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" ``` ## 2) Получить Merchant UUID и Payment API Key в Heleket 1. Откройте кабинет Heleket. 2. Создайте/выберите merchant проект. 3. Скопируйте Merchant UUID. 4. Сгенерируйте Payment API Key. Важно: ключ и UUID должны относиться к одному merchant-проекту. ## 3) Подтверждение домена (meta-тег) Если Heleket требует подтверждение домена через мета-тег: 1. Получите значение тега в кабинете Heleket. 2. Задайте переменную окружения: ```env HELEKET_DOMAIN_META="" ``` 3. Перезапустите приложение и убедитесь, что в `` присутствует meta `heleket`. После прохождения модерации переменную можно очистить. ## 4) Включить Heleket в админке Откройте `Admin -> Heleket` и заполните: - `Merchant UUID` — в поле `merchantId`; - `Payment API Key` — в поле `apiKey`; - `Fiat` (обычно `USD`); - `toCurrency` и `cryptoNetwork` (опционально); - `invoiceExpiresInSec`. Нажмите `Сохранить`, затем `Проверить`. Endpoint проверки: `POST /api/admin/billing/providers/heleket/test` Проверка выполняет безопасный read-only вызов `POST /v1/payment/services`. ## 5) Webhook Webhook URL выдаётся в админке: ```text https:///api/billing/providers/heleket/webhook/ ``` Эта ссылка используется сервером как `url_callback` при создании каждого инвойса. Подпись webhook: - передаётся в теле в поле `sign`; - проверяется через `heleketVerifyWebhookSign`; - алгоритм: `md5(base64(json-with-escaped-slashes) + apiKey)`. IP-check: - allowlist: `31.133.220.8`; - контролируется `HELEKET_STRICT_IP_CHECK`; - по умолчанию `true` в production, `false` в dev/test. ## 6) Проверка рабочего сценария 1. В админке включите Heleket. 2. На странице тарифов убедитесь, что метод `Heleket` доступен. 3. Создайте checkout с `provider=HELEKET`. 4. Убедитесь, что создан `BillingInvoice` с `order_id = BillingInvoice.id`. 5. Отправьте webhook `paid`/`paid_over` и проверьте активацию entitlement. ## 7) Troubleshooting - `HELEKET_MERCHANT_MISSING` — не задан Merchant UUID. - `HELEKET_API_KEY_MISSING` / `HELEKET_TOKEN_NOT_CONFIGURED` — не задан API Key. - `HELEKET_WEBHOOK_SIGNATURE_INVALID` — неверная подпись webhook. - `HELEKET_WEBHOOK_IP_NOT_ALLOWED` — webhook пришёл не с allowlist IP при strict режиме. - `HELEKET_WEBHOOK_INVALID_JSON` — webhook отправлен невалидным JSON.