diff --git a/docs/features/payments.md b/docs/features/payments.md index e8d07b1..ce8d4ee 100644 --- a/docs/features/payments.md +++ b/docs/features/payments.md @@ -18,6 +18,23 @@ - [Тарифы](tariffs.md) описывают цены, Telegram Stars и сценарии покупки. - [Логи](../troubleshooting/logs.md) помогают проверить webhook и создание платежных ссылок. +## Webhook URL провайдеров + +Все платежные webhook URL строятся от `WEBHOOK_BASE_URL` - публичного HTTPS-адреса backend/webhook-домена. Это должен быть домен, который проксируется на backend-сервер вебхуков (`backend:8080`), а не `SUBSCRIPTION_MINI_APP_URL` frontend/Mini App. Если `WEBHOOK_BASE_URL=https://bot.example.com`, то полный адрес получается как `https://bot.example.com` + путь из таблицы. + +| Провайдер | Что указать в кабинете провайдера | Комментарий | +| --- | --- | --- | +| YooKassa | `WEBHOOK_BASE_URL` + `/webhook/yookassa` | Например `https://bot.example.com/webhook/yookassa`. | +| FreeKassa | `WEBHOOK_BASE_URL` + `/webhook/freekassa` | Используйте как notification/webhook URL; при IP-фильтрации заполните `FREEKASSA_TRUSTED_IPS`. | +| Platega | `WEBHOOK_BASE_URL` + `/webhook/platega` | Один общий webhook для основной, СБП/карты и crypto-кнопки Platega. | +| SeverPay | `WEBHOOK_BASE_URL` + `/webhook/severpay` | Укажите как callback/webhook URL, если поле есть в кабинете мерчанта. | +| Wata | `WEBHOOK_BASE_URL` + `/webhook/wata` | Если включена проверка подписи, настройте `WATA_WEBHOOK_VERIFY_SIGNATURE` и `WATA_PUBLIC_KEY`. | +| CryptoPay | `WEBHOOK_BASE_URL` + `/webhook/cryptopay` | Указывается в настройках Crypto Bot / CryptoPay webhook. | +| Heleket | `WEBHOOK_BASE_URL` + `/webhook/heleket` | При необходимости включите `HELEKET_VERIFY_WEBHOOK_SIGNATURE` и `HELEKET_TRUSTED_IPS`. | +| Telegram Stars | Отдельный платежный webhook не нужен | Stars-события приходят через webhook Telegram-бота: `WEBHOOK_BASE_URL` + `/tg/webhook`. | + +После настройки сделайте тестовый платеж и проверьте, что в логах `backend` видно входящий `POST` на нужный путь. Если провайдер сообщает, что адрес недоступен, сначала проверьте DNS/HTTPS и reverse proxy для `WEBHOOK_BASE_URL`, затем убедитесь, что путь начинается ровно с `/webhook/...` без `/api`, `/auth` и frontend-домена. + ## YooKassa YooKassa используется для рублевых оплат и может участвовать в сценариях автопродления period-подписок. @@ -26,7 +43,7 @@ YooKassa используется для рублевых оплат и може - включение провайдера: `YOOKASSA_ENABLED`; - идентификаторы и секреты магазина; -- URL вебхука на backend-домен; +- URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/yookassa`; - отображение кнопки оплаты и порядок платежных методов. Справочник переменных: [YooKassa](../configuration/env-vars.md#yookassa). @@ -40,7 +57,7 @@ FreeKassa подключается как отдельный платежный - включение провайдера: `FREEKASSA_ENABLED`; - ID магазина, API/secret-ключи и настройки подписи; - список доверенных IP, если используется; -- публичный URL вебхука на `WEBHOOK_BASE_URL`. +- публичный URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/freekassa`. Справочник переменных: [FreeKassa](../configuration/env-vars.md#freekassa). @@ -60,8 +77,9 @@ Platega подключается как отдельный платежный п 1. Укажите `PLATEGA_BASE_URL`, `PLATEGA_MERCHANT_ID` и `PLATEGA_SECRET`. 2. Заполните `PLATEGA_SBP_METHOD` и/или `PLATEGA_CRYPTO_METHOD`, если используете отдельные кнопки. 3. Проверьте `PLATEGA_RETURN_URL` и `PLATEGA_FAILED_URL`. -4. Настройте тексты и иконки кнопок через `PAYMENT_PLATEGA_SBP_*` и `PAYMENT_PLATEGA_CRYPTO_*`. -5. Добавьте нужные методы в `PAYMENT_METHODS_ORDER`. +4. Укажите URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/platega`. +5. Настройте тексты и иконки кнопок через `PAYMENT_PLATEGA_SBP_*` и `PAYMENT_PLATEGA_CRYPTO_*`. +6. Добавьте нужные методы в `PAYMENT_METHODS_ORDER`. Справочник переменных: [Platega](../configuration/env-vars.md#platega). @@ -75,8 +93,9 @@ SeverPay подключается как отдельный платежный 2. Укажите `SEVERPAY_BASE_URL`. 3. Заполните `SEVERPAY_MID` и `SEVERPAY_TOKEN`. 4. Настройте `SEVERPAY_RETURN_URL`. -5. При необходимости задайте `SEVERPAY_LIFETIME_MINUTES`. -6. Добавьте `severpay` в `PAYMENT_METHODS_ORDER`. +5. Укажите URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/severpay`. +6. При необходимости задайте `SEVERPAY_LIFETIME_MINUTES`. +7. Добавьте `severpay` в `PAYMENT_METHODS_ORDER`. Справочник переменных: [SeverPay](../configuration/env-vars.md#severpay). @@ -90,9 +109,10 @@ Wata подключается как отдельный провайдер с be 2. Укажите `WATA_BASE_URL` и `WATA_API_TOKEN`. 3. Проверьте `WATA_RETURN_URL` и `WATA_FAILED_URL`. 4. Настройте `WATA_LINK_TTL_MINUTES`: минимум 15 минут, максимум 43200. -5. Если включаете проверку подписи, задайте `WATA_WEBHOOK_VERIFY_SIGNATURE` и при необходимости `WATA_PUBLIC_KEY`. -6. Для дополнительной защиты заполните `WATA_TRUSTED_IPS`. -7. Добавьте `wata` в `PAYMENT_METHODS_ORDER`. +5. Укажите URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/wata`. +6. Если включаете проверку подписи, задайте `WATA_WEBHOOK_VERIFY_SIGNATURE` и при необходимости `WATA_PUBLIC_KEY`. +7. Для дополнительной защиты заполните `WATA_TRUSTED_IPS`. +8. Добавьте `wata` в `PAYMENT_METHODS_ORDER`. Справочник переменных: [Wata](../configuration/env-vars.md#wata). @@ -107,7 +127,8 @@ CryptoPay используется для криптовалютных плат 3. Выберите `CRYPTOPAY_NETWORK`: `mainnet` или `testnet`. 4. Задайте `CRYPTOPAY_CURRENCY_TYPE`: `fiat` или `crypto`. 5. Проверьте `CRYPTOPAY_ASSET`, например `RUB`, `USDT` или `BTC`. -6. Добавьте `cryptopay` в `PAYMENT_METHODS_ORDER`. +6. Укажите URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/cryptopay`. +7. Добавьте `cryptopay` в `PAYMENT_METHODS_ORDER`. Для тестов используйте соответствующую сеть: testnet-токен не должен попадать в mainnet-настройки. Если сумма или asset выглядят неверно, проверьте сочетание `CRYPTOPAY_CURRENCY_TYPE` и `CRYPTOPAY_ASSET`. @@ -125,9 +146,10 @@ Heleket используется для крипто-инвойсов с отд 4. При необходимости задайте `HELEKET_TO_CURRENCY` и `HELEKET_NETWORK`. 5. Проверьте `HELEKET_RETURN_URL` и `HELEKET_SUCCESS_URL`. 6. Настройте `HELEKET_LIFETIME_SECONDS`: допустимый диапазон 300..43200. -7. Если включаете проверку webhook, задайте `HELEKET_VERIFY_WEBHOOK_SIGNATURE`. -8. Для IP-фильтрации заполните `HELEKET_TRUSTED_IPS`. -9. Добавьте `heleket` в `PAYMENT_METHODS_ORDER`. +7. Укажите URL вебхука: `WEBHOOK_BASE_URL` + `/webhook/heleket`. +8. Если включаете проверку webhook, задайте `HELEKET_VERIFY_WEBHOOK_SIGNATURE`. +9. Для IP-фильтрации заполните `HELEKET_TRUSTED_IPS`. +10. Добавьте `heleket` в `PAYMENT_METHODS_ORDER`. Справочник переменных: [Heleket](../configuration/env-vars.md#heleket). @@ -145,6 +167,7 @@ Telegram Stars используются напрямую и поддержива Что проверить: - `STARS_ENABLED`; +- отдельный платежный webhook не настраивается: Telegram Stars приходят через webhook Telegram-бота `WEBHOOK_BASE_URL` + `/tg/webhook`; - Stars-цены в legacy-настройках или JSON-каталоге; - корректное округление цены до целого количества Stars; - сценарии смены тарифа: XTR/Stars-докупки не конвертируются без явного курса.