From 0afe4f0bc532a1035ef4cbf2a213314655e9c2b6 Mon Sep 17 00:00:00 2001 From: BADtochka <75701093+BADtochka@users.noreply.github.com> Date: Thu, 4 Jun 2026 15:46:47 +0300 Subject: [PATCH] docs: payments structure Updated payment methods documentation for clarity and consistency. Adjusted setup instructions and links for better readability. --- docs/features/payments.md | 170 ++++++++++++++++++++++---------------- 1 file changed, 98 insertions(+), 72 deletions(-) diff --git a/docs/features/payments.md b/docs/features/payments.md index e8d07b1..3e7dae1 100644 --- a/docs/features/payments.md +++ b/docs/features/payments.md @@ -1,152 +1,178 @@ # Платежи -Платежные методы включаются настройками и отображаются пользователю как кнопки оплаты в Mini App и Telegram-сценариях. Настройки можно задавать через `.env` или через админку, если параметр есть в allowlist настроек. +Платежные методы включаются через `.env` или админ-панель, если параметр добавлен в allowlist настроек. В Mini App и Telegram-сценариях включённые методы отображаются как кнопки оплаты. -## Типовой порядок настройки +## Общий порядок настройки -1. Включите нужный провайдер в админке или через `.env`. +1. Включите нужный провайдер. 2. Заполните публичные параметры, секреты и URL возврата. -3. Настройте URL вебхука у провайдера, если это требуется. +3. Настройте webhook URL у провайдера, если он используется. 4. Проверьте порядок методов в `PAYMENT_METHODS_ORDER`. 5. Проверьте подписи и иконки кнопок оплаты. -6. Выполните тестовый платеж и проверьте логи `backend`. +6. Выполните тестовый платеж. +7. Проверьте логи `backend`. -Общие ссылки: +> [!TIP] +> URL вебхука отображается вверху раздела каждого провайдера в админ-панели. -- [Справочник `.env`](../configuration/env-vars.md) содержит все ключи провайдеров. -- [Админ-панель](admin-panel.md) описывает UI-настройки платежей. -- [Тарифы](tariffs.md) описывают цены, Telegram Stars и сценарии покупки. -- [Логи](../troubleshooting/logs.md) помогают проверить webhook и создание платежных ссылок. +## Общие ссылки + +- [Справочник `.env`](../configuration/env-vars.md) — все ключи платежных провайдеров. +- [Админ-панель](admin-panel.md) — UI-настройки платежей. +- [Тарифы](tariffs.md) — цены, Telegram Stars и сценарии покупки. +- [Логи](../troubleshooting/logs.md) — проверка webhook и создания платежных ссылок. ## YooKassa -YooKassa используется для рублевых оплат и может участвовать в сценариях автопродления period-подписок. +YooKassa используется для рублевых оплат. Провайдер также может участвовать в сценариях автопродления period-подписок. -Что настроить: +### Настройка -- включение провайдера: `YOOKASSA_ENABLED`; -- идентификаторы и секреты магазина; -- URL вебхука на backend-домен; -- отображение кнопки оплаты и порядок платежных методов. +1. Включите `YOOKASSA_ENABLED`. +2. Заполните `YOOKASSA_SHOP_ID`, `YOOKASSA_SECRET_KEY`, `YOOKASSA_RETURN_URL`. +3. Скопируйте URL вебхука из админ-панели и укажите его в кабинете YooKassa. -Справочник переменных: [YooKassa](../configuration/env-vars.md#yookassa). +### Справочник + +- [YooKassa](../configuration/env-vars.md#yookassa) ## FreeKassa -FreeKassa подключается как отдельный платежный метод и обрабатывает входящие webhook-события через `backend`. +FreeKassa подключается как отдельный платежный метод. Входящие webhook-события обрабатываются через `backend`. -Что настроить: +### Настройка -- включение провайдера: `FREEKASSA_ENABLED`; -- ID магазина, API/secret-ключи и настройки подписи; -- список доверенных IP, если используется; -- публичный URL вебхука на `WEBHOOK_BASE_URL`. +1. Включите `FREEKASSA_ENABLED`. +2. Заполните `FREEKASSA_MERCHANT_ID`, `FREEKASSA_FIRST_SECRET`, `FREEKASSA_SECOND_SECRET`, `FREEKASSA_API_KEY`. +3. Проверьте настройки подписи. +4. Скопируйте URL вебхука из админ-панели и укажите его в кабинете FreeKassa. +5. При необходимости заполните список доверенных IP. -Справочник переменных: [FreeKassa](../configuration/env-vars.md#freekassa). +### Справочник + +- [FreeKassa](../configuration/env-vars.md#freekassa) ## Platega -Platega подключается как отдельный платежный провайдер, но внутри Minishop может дать несколько кнопок: основную устаревшую кнопку, СБП/карту и крипто-кнопку. Общие параметры мерчанта задаются один раз, а ID методов оплаты и подписи кнопок настраиваются отдельно. +Platega подключается как отдельный платежный провайдер. Внутри Minishop он может создавать несколько кнопок: основную legacy-кнопку, СБП/карту и crypto-кнопку. -Что включить: +### Настройка -- `PLATEGA_ENABLED` - общий флаг провайдера; -- `PLATEGA_SBP_ENABLED` - отдельная кнопка СБП/карта; -- `PLATEGA_CRYPTO_ENABLED` - отдельная crypto-кнопка Platega; -- `PLATEGA_PAYMENT_METHOD` - устаревший/резервный ID метода оплаты для старых callback-запросов и старых установок. +1. Включите `PLATEGA_ENABLED`. +2. Укажите `PLATEGA_MERCHANT_ID` и `PLATEGA_SECRET`. +3. Скопируйте URL вебхука из админ-панели и укажите его в кабинете Platega. +4. Проверьте `PLATEGA_RETURN_URL` и `PLATEGA_FAILED_URL`. +5. При необходимости укажите `PLATEGA_PAYMENT_METHOD`. -Что настроить: +### Справочник -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`. - -Справочник переменных: [Platega](../configuration/env-vars.md#platega). +- [Platega](../configuration/env-vars.md#platega) ## SeverPay SeverPay подключается как отдельный платежный метод с собственным MID, token и сроком жизни платежной ссылки. -Что настроить: +### Настройка 1. Включите `SEVERPAY_ENABLED`. -2. Укажите `SEVERPAY_BASE_URL`. -3. Заполните `SEVERPAY_MID` и `SEVERPAY_TOKEN`. -4. Настройте `SEVERPAY_RETURN_URL`. -5. При необходимости задайте `SEVERPAY_LIFETIME_MINUTES`. -6. Добавьте `severpay` в `PAYMENT_METHODS_ORDER`. +2. Укажите `SEVERPAY_MID`, `SEVERPAY_TOKEN`, `SEVERPAY_BASE_URL` +3. Скопируйте URL вебхука из админ-панели и укажите его в кабинете SeverPay. +4. При необходимости задайте `SEVERPAY_LIFETIME_MINUTES`. -Справочник переменных: [SeverPay](../configuration/env-vars.md#severpay). +### Справочник + +- [SeverPay](../configuration/env-vars.md#severpay) ## Wata Wata подключается как отдельный провайдер с bearer token, платежными ссылками и опциональной проверкой подписи webhook. -Что настроить: +### Настройка 1. Включите `WATA_ENABLED`. 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`. +4. Настройте `WATA_LINK_TTL_MINUTES`. +5. При необходимости включите `WATA_WEBHOOK_VERIFY_SIGNATURE`. +6. Если используется проверка подписи, задайте `WATA_PUBLIC_KEY`. +7. Для IP-фильтрации заполните `WATA_TRUSTED_IPS`. -Справочник переменных: [Wata](../configuration/env-vars.md#wata). +### Ограничения + +- `WATA_LINK_TTL_MINUTES` должен быть от `15` до `43200`. + +### Справочник + +- [Wata](../configuration/env-vars.md#wata) ## CryptoPay CryptoPay используется для криптовалютных платежей через отдельный токен и сеть Crypto Bot API. -Что настроить: +### Настройка 1. Включите `CRYPTOPAY_ENABLED`. 2. Укажите `CRYPTOPAY_TOKEN`. 3. Выберите `CRYPTOPAY_NETWORK`: `mainnet` или `testnet`. 4. Задайте `CRYPTOPAY_CURRENCY_TYPE`: `fiat` или `crypto`. -5. Проверьте `CRYPTOPAY_ASSET`, например `RUB`, `USDT` или `BTC`. -6. Добавьте `cryptopay` в `PAYMENT_METHODS_ORDER`. +5. Проверьте `CRYPTOPAY_ASSET`. -Для тестов используйте соответствующую сеть: testnet-токен не должен попадать в mainnet-настройки. Если сумма или asset выглядят неверно, проверьте сочетание `CRYPTOPAY_CURRENCY_TYPE` и `CRYPTOPAY_ASSET`. +### Проверка -Справочник переменных: [CryptoPay](../configuration/env-vars.md#cryptopay). +- Testnet-токен должен использоваться только с `testnet`. +- Mainnet-токен должен использоваться только с `mainnet`. +- Если сумма или asset выглядят неверно, проверьте сочетание `CRYPTOPAY_CURRENCY_TYPE` и `CRYPTOPAY_ASSET`. + +### Справочник + +- [CryptoPay](../configuration/env-vars.md#cryptopay) ## Heleket -Heleket используется для крипто-инвойсов с отдельными merchant ID, ключом платежного API, валютой инвойса и настройками проверки webhook. +Heleket используется для крипто-инвойсов с merchant ID, ключом платежного API, валютой инвойса и настройками проверки webhook. -Что настроить: +### Настройка 1. Включите `HELEKET_ENABLED`. 2. Укажите `HELEKET_BASE_URL`, `HELEKET_MERCHANT_ID` и `HELEKET_API_KEY`. 3. Настройте `HELEKET_CURRENCY`. 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`. +6. Настройте `HELEKET_LIFETIME_SECONDS`. +7. При необходимости включите `HELEKET_VERIFY_WEBHOOK_SIGNATURE`. 8. Для IP-фильтрации заполните `HELEKET_TRUSTED_IPS`. -9. Добавьте `heleket` в `PAYMENT_METHODS_ORDER`. -Справочник переменных: [Heleket](../configuration/env-vars.md#heleket). +### Ограничения + +- `HELEKET_LIFETIME_SECONDS` должен быть от `300` до `43200`. + +### Справочник + +- [Heleket](../configuration/env-vars.md#heleket) ## Telegram Stars Telegram Stars используются напрямую и поддерживаются в legacy-ценах и JSON-каталоге тарифов. -Где применяются Stars: +### Где используются -- цены периодов подписки; -- пакеты трафика; -- premium-докупки; +- Цены period-подписок. +- Пакеты трафика. +- Premium-докупки. - HWID-докупки, если они включены в каталоге тарифов. -Что проверить: +### Настройка -- `STARS_ENABLED`; -- Stars-цены в legacy-настройках или JSON-каталоге; -- корректное округление цены до целого количества Stars; -- сценарии смены тарифа: XTR/Stars-докупки не конвертируются без явного курса. +1. Включите `STARS_ENABLED`. +2. Проверьте Stars-цены в legacy-настройках или JSON-каталоге. +3. Убедитесь, что цена округляется до целого количества Stars. +4. Проверьте сценарии смены тарифа. -См. также [переменные платежей](../configuration/env-vars.md#платежи) и [тарифы](tariffs.md). +### Ограничения + +- XTR/Stars-докупки не конвертируются без явно заданного курса. + +### Справочник + +- [Переменные платежей](../configuration/env-vars.md#платежи) +- [Тарифы](tariffs.md)