austnv/remnawave-minishop
1
0
Fork 0
Code Issues 1 Pull Requests Activity

docs: document payment provider webhook URLs

Browse Source
This commit is contained in:
3252a8
2026-06-03 23:55:08 +03:00
parent fbb89793cb
commit 5f22c2081e
1 changed files with 36 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/payments.md
+36 -13
View File
@@ -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-докупки не конвертируются без явного курса.