> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedolagam.ru/llms.txt
> Use this file to discover all available pages before exploring further.
# Настройка платежей
> Подключение платёжных систем, настройки баланса, автооплаты и webhook
Бот поддерживает 23 платёжных провайдера одновременно (плюс Apple In-App Purchase). Каждый провайдер включается отдельно, все работают параллельно через единый веб-сервер на порту `8080`.
## Общая архитектура
Все платежи проходят через **баланс**: пользователь пополняет баланс любым доступным способом, затем покупает подписку с баланса.
Единственное исключение —**Telegram Stars** и **простая подписка** (`SIMPLE_SUBSCRIPTION_ENABLED`), которые могут проводить оплату напрямую, минуя баланс.
```
Пользователь → Выбор способа оплаты → Провайдер → Webhook → Зачисление на баланс
↓
Автопокупка (если включена)
↓
Активация подписки
```
### Приоритет отображения
Способы оплаты отображаются в фиксированном порядке:
1. Telegram Stars
2. YooKassa СБП (если `YOOKASSA_SBP_ENABLED=true`)
3. YooKassa карты
4. Tribute
5. MulenPay
6. WATA
7. PayPalych (Pal24)
8. CryptoBot
9. Heleket
10. Platega
11. CloudPayments
12. Freekassa
13. Kassa AI
14. RioPay
15. SeverPay
16. PayPear
17. RollyPay
18. AuraPay
19. Overpay
20. Etoplatezhi
21. Antilopay
22. Jupiter
23. Donut
24. Lava
25. Apple In-App Purchase (только iOS, отображается в Mini App)
26. Через поддержку (всегда последний)
***
## Поддерживаемые провайдеры
| Провайдер | Методы оплаты | Webhook URL | Валюта |
| --------------------- | ------------------------------ | ------------------------ | ---------- |
| Telegram Stars | Звёзды Telegram | (встроенный) | XTR |
| YooKassa | Карты, СБП | `/yookassa-webhook` | RUB |
| CryptoBot | USDT, TON, BTC, ETH | `/cryptobot-webhook` | Крипто |
| CloudPayments | Карты, 3D-Secure | `/cloudpayments-webhook` | RUB |
| Freekassa | NSPK СБП, карты | `/freekassa-webhook` | RUB |
| Kassa AI | СБП, карты, SberPay | `/kassa-ai-webhook` | RUB |
| PayPalych (Pal24) | Карты, СБП | `/pal24-webhook` | RUB |
| Platega | Карты, СБП, крипто | `/platega-webhook` | RUB |
| WATA | Карты | `/wata-webhook` | RUB |
| Heleket | Криптовалюта | `/heleket-webhook` | Крипто |
| MulenPay | Карты | `/mulenpay-webhook` | RUB |
| Tribute | Telegram | `/tribute-webhook` | RUB |
| RioPay | Карты | `/riopay-webhook` | RUB |
| SeverPay | СБП, карты | `/severpay-webhook` | RUB |
| PayPear | Карты, СБП, SberPay, T-Pay | `/paypear-webhook` | RUB |
| RollyPay | СБП, карты, крипто | `/rollypay-webhook` | RUB → USDT |
| AuraPay | Карты, СБП | `/aurapay-webhook` | RUB |
| Overpay | Карты, СБП | `/overpay-webhook` | RUB |
| Etoplatezhi | Карты, СБП | `/etoplatezhi-webhook` | RUB |
| Antilopay | Карты, СБП, SberPay (RSA) | `/antilopay-webhook` | RUB |
| Jupiter (FPGate P2P) | СБП через QR-код | `/jupiter-webhook` | RUB |
| Donut (Donut P2P) | Карты, СБП по телефону, СБП QR | `/donut-webhook` | RUB |
| Lava Business | Карты, СБП | `/lava-webhook` | RUB |
| Apple In-App Purchase | Покупки через iOS App Store | (App Store Server API) | USD |
Все webhook URL доступны на едином сервере бота (порт 8080). Укажите полный путь: `https://hooks.domain.com/webhook-path`. Для CloudPayments дополнительно доступны суб-роуты `/check`, `/pay`, `/fail`.
***
## Общие настройки платежей
Эти переменные влияют на все платёжные системы.
### Описания и шаблоны платежей
```env theme={null}
# Название сервиса в описании платежа
PAYMENT_SERVICE_NAME=Интернет-сервис
# Описания для разных типов платежей
PAYMENT_BALANCE_DESCRIPTION=Пополнение баланса
PAYMENT_SUBSCRIPTION_DESCRIPTION=Оплата подписки
# Шаблоны формирования описания (переменные: {service_name}, {description})
PAYMENT_BALANCE_TEMPLATE={service_name} - {description}
PAYMENT_SUBSCRIPTION_TEMPLATE={service_name} - {description}
```
### Управление интерфейсом
| Переменная | Тип | По умолчанию | Описание |
| ------------------------ | ------ | ------------ | --------------------------------------------------- |
| `DISABLE_TOPUP_BUTTONS` | `bool` | `false` | Скрыть кнопки быстрого пополнения |
| `SUPPORT_TOPUP_ENABLED` | `bool` | `true` | Показывать кнопку "Через поддержку" |
| `PRICE_ROUNDING_ENABLED` | `bool` | `true` | Округление цен (до 50 коп вниз, свыше 50 коп вверх) |
### Автопроверка платежей
```env theme={null}
# Автоматическая проверка статуса незавершённых платежей (YooKassa)
PAYMENT_VERIFICATION_AUTO_CHECK_ENABLED=false
PAYMENT_VERIFICATION_AUTO_CHECK_INTERVAL_MINUTES=10
```
### Автопокупка после пополнения
```env theme={null}
# Автоматически оформить подписку из сохранённой корзины после пополнения баланса
AUTO_PURCHASE_AFTER_TOPUP_ENABLED=false
```
Подробнее — см. [Автопокупка и корзина](/bot/auto-purchase).
### Автооплата (автопродление)
Подробнее — см. [Рекуррентные платежи](/bot/recurrent-payments).
| Переменная | Тип | По умолчанию | Описание |
| ----------------------------------------------- | ------ | ------------ | ------------------------------------------------------ |
| `ENABLE_AUTOPAY` | `bool` | `false` | Глобальное включение системы автопродления |
| `DEFAULT_AUTOPAY_ENABLED` | `bool` | `false` | Автооплата включена у новых пользователей по умолчанию |
| `DEFAULT_AUTOPAY_DAYS_BEFORE` | `int` | `3` | За сколько дней до окончания подписки списывать |
| `MIN_BALANCE_FOR_AUTOPAY_KOPEKS` | `int` | `10000` | Минимальный баланс для срабатывания (100 руб) |
| `SUBSCRIPTION_RENEWAL_BALANCE_THRESHOLD_KOPEKS` | `int` | `20000` | Порог баланса для автопродления (200 руб) |
| `AUTOPAY_WARNING_DAYS` | `str` | `3,1` | Дни для отправки предупреждений (через запятую) |
***
## Telegram Stars
Встроенная платёжная система Telegram. Не требует webhook — платежи обрабатываются через Telegram Bot API.
### Настройки
| Переменная | Тип | По умолчанию | Описание |
| ----------------------------- | ------- | ---------------- | ------------------------- |
| `TELEGRAM_STARS_ENABLED` | `bool` | `true` | Включить оплату звёздами |
| `TELEGRAM_STARS_RATE_RUB` | `float` | `1.3` | Курс: 1 звезда = X рублей |
| `TELEGRAM_STARS_DISPLAY_NAME` | `str` | `Telegram Stars` | Отображаемое название |
Telegram Stars — единственный провайдер, включённый по умолчанию. Курс `1.3` означает: 1 звезда = 1.30 руб. Количество звёзд рассчитывается автоматически на основе суммы в рублях.
### Округление и нормализация суммы
Количество звёзд рассчитывается из суммы в рублях с помощью стандартного округления (`round()`):
```
звёзды = round(сумма_в_рублях / курс)
```
Например, при курсе `1.79` за звезду и сумме 500₽: `round(500 / 1.79)` = 279 звёзд.
При зачислении сумма **нормализуется**: на баланс попадает не исходная сумма, а точный эквивалент оплаченных звёзд: `звёзды × курс`. В примере выше: `279 × 1.79` = 499.41₽, а не 500₽.
Это означает, что пользователь получает ровно столько, сколько стоят оплаченные звёзды. Небольшая разница между запрошенной и зачисленной суммой — следствие округления при конвертации.
### Особенности
* Работает без внешних webhook и API-ключей
* Поддерживает как пополнение баланса, так и прямую оплату простых подписок
* Валюта: `XTR` (Telegram Stars)
* Минимум: 1 звезда
***
## YooKassa
Самый популярный провайдер для российского рынка. Поддерживает банковские карты, СБП, и фискализацию через НалоGo.
### Обязательные настройки
```env theme={null}
YOOKASSA_ENABLED=true
YOOKASSA_SHOP_ID=123456
YOOKASSA_SECRET_KEY=live_xxxxxxxxxxxxx
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| ----------------------------------------- | ------ | ------------------- | ------------------------------------------------------------------------------------------ |
| `YOOKASSA_ENABLED` | `bool` | `false` | Включить YooKassa |
| `YOOKASSA_SHOP_ID` | `str` | — | **Обязательно**. ID магазина |
| `YOOKASSA_SECRET_KEY` | `str` | — | **Обязательно**. Секретный ключ |
| `YOOKASSA_DISPLAY_NAME` | `str` | `YooKassa` | Отображаемое название |
| `YOOKASSA_RETURN_URL` | `str` | — | URL возврата после оплаты (по умолчанию `WEBHOOK_URL/payment-success` или `https://t.me/`) |
| `YOOKASSA_DEFAULT_RECEIPT_EMAIL` | `str` | — | Email для отправки чеков (54-ФЗ) |
| `YOOKASSA_VAT_CODE` | `int` | `1` | Код НДС (1=без НДС, 2=0%, 3=10%, 4=20%) |
| `YOOKASSA_SBP_ENABLED` | `bool` | `false` | Включить оплату через СБП (отдельная кнопка) |
| `YOOKASSA_PAYMENT_MODE` | `str` | `full_payment` | Режим оплаты для чеков |
| `YOOKASSA_PAYMENT_SUBJECT` | `str` | `service` | Тип предмета расчёта для чеков |
| `YOOKASSA_WEBHOOK_PATH` | `str` | `/yookassa-webhook` | Путь webhook |
| `YOOKASSA_WEBHOOK_HOST` | `str` | `0.0.0.0` | Хост для webhook |
| `YOOKASSA_WEBHOOK_PORT` | `int` | `8082` | Порт (устаревший, используется 8080) |
| `YOOKASSA_TRUSTED_PROXY_NETWORKS` | `str` | — | Доверенные сети прокси (через запятую) |
| `YOOKASSA_MIN_AMOUNT_KOPEKS` | `int` | `5000` | Минимальная сумма (50 руб) |
| `YOOKASSA_MAX_AMOUNT_KOPEKS` | `int` | `1000000` | Максимальная сумма (10 000 руб) |
| `YOOKASSA_QUICK_AMOUNT_SELECTION_ENABLED` | `bool` | `false` | Кнопки быстрого выбора суммы |
### Webhook
Укажите в кабинете YooKassa: `https://hooks.domain.com/yookassa-webhook`
Бот проверяет IP-адреса YooKassa и отклоняет запросы с неизвестных адресов. При использовании reverse proxy укажите сети прокси в `YOOKASSA_TRUSTED_PROXY_NETWORKS`.
### Рекуррентные платежи (сохранённые карты)
YooKassa поддерживает сохранение банковских карт для автоматического пополнения баланса при продлении подписки. Подробнее — см. [Рекуррентные платежи](/bot/recurrent-payments).
| Переменная | Тип | По умолчанию | Описание |
| ----------------------------- | ------ | ------------ | --------------------------------------------------------------------------------- |
| `YOOKASSA_RECURRENT_ENABLED` | `bool` | `false` | Включить сохранение карт и рекуррентные платежи |
| `YOOKASSA_RECURRENT_REQUIRED` | `bool` | `false` | Всегда запрашивать сохранение карты при оплате |
| `YOOKASSA_TEST_MODE` | `bool` | `false` | Тестовый режим (принимать тестовые платежи). В проде тестовые платежи отклоняются |
При включённом `YOOKASSA_RECURRENT_ENABLED`:
* При успешной оплате карта автоматически сохраняется (если пользователь дал согласие или `RECURRENT_REQUIRED=true`)
* Сохранённые карты используются для автоматического пополнения баланса при продлении подписки
* Работает совместно с системой автооплаты (`ENABLE_AUTOPAY=true`): если у пользователя недостаточно баланса для продления, бот автоматически списывает нужную сумму с сохранённой карты
* Пользователь может управлять сохранёнными картами (удалять ненужные)
Для работы рекуррентных платежей необходимо одновременно включить `YOOKASSA_RECURRENT_ENABLED=true` и `ENABLE_AUTOPAY=true`. Без автооплаты сохранённые карты не будут использоваться автоматически.
### Фискализация (НалоGo)
YooKassa поддерживает автоматическую отправку чеков через НалоGo (для самозанятых):
```env theme={null}
NALOGO_ENABLED=true
NALOGO_INN=123456789012
NALOGO_PASSWORD=your_password
NALOGO_DEVICE_ID=optional_device_id
NALOGO_STORAGE_PATH=./nalogo_tokens.json
```
| Переменная | Тип | По умолчанию | Описание |
| --------------------- | ------ | ---------------------- | ------------------------------------------ |
| `NALOGO_ENABLED` | `bool` | `false` | Включить отправку чеков |
| `NALOGO_INN` | `str` | — | **Обязательно**. ИНН самозанятого |
| `NALOGO_PASSWORD` | `str` | — | **Обязательно**. Пароль от ЛК Мой Налог |
| `NALOGO_DEVICE_ID` | `str` | — | ID устройства (генерируется автоматически) |
| `NALOGO_STORAGE_PATH` | `str` | `./nalogo_tokens.json` | Путь хранения токенов |
Настройки очереди чеков:
| Переменная | Тип | По умолчанию | Описание |
| ----------------------------- | ----- | ------------ | ---------------------------------------- |
| `NALOGO_QUEUE_CHECK_INTERVAL` | `int` | `300` | Интервал проверки очереди (секунды) |
| `NALOGO_QUEUE_RECEIPT_DELAY` | `int` | `3` | Задержка между отправкой чеков (секунды) |
| `NALOGO_QUEUE_MAX_ATTEMPTS` | `int` | `10` | Максимум попыток отправки чека |
***
## CryptoBot
Криптовалютные платежи через [CryptoBot](https://t.me/CryptoBot).
### Обязательные настройки
```env theme={null}
CRYPTOBOT_ENABLED=true
CRYPTOBOT_API_TOKEN=your_token
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| --------------------------------- | ------ | ----------------------- | ---------------------------------------------------- |
| `CRYPTOBOT_ENABLED` | `bool` | `false` | Включить CryptoBot |
| `CRYPTOBOT_API_TOKEN` | `str` | — | **Обязательно**. API-токен из @CryptoBot |
| `CRYPTOBOT_DISPLAY_NAME` | `str` | `CryptoBot` | Отображаемое название |
| `CRYPTOBOT_WEBHOOK_SECRET` | `str` | — | Секрет для проверки webhook |
| `CRYPTOBOT_BASE_URL` | `str` | `https://pay.crypt.bot` | Базовый URL API |
| `CRYPTOBOT_TESTNET` | `bool` | `false` | Использовать тестовую сеть (`testnet-pay.crypt.bot`) |
| `CRYPTOBOT_WEBHOOK_PATH` | `str` | `/cryptobot-webhook` | Путь webhook |
| `CRYPTOBOT_WEBHOOK_PORT` | `int` | `8083` | Порт (устаревший, используется 8080) |
| `CRYPTOBOT_DEFAULT_ASSET` | `str` | `USDT` | Криптовалюта по умолчанию |
| `CRYPTOBOT_ASSETS` | `str` | `USDT,TON,BTC,ETH` | Доступные криптовалюты (через запятую) |
| `CRYPTOBOT_INVOICE_EXPIRES_HOURS` | `int` | `24` | Время жизни инвойса (часы) |
### Тестовый режим
```env theme={null}
CRYPTOBOT_TESTNET=true
```
При `CRYPTOBOT_TESTNET=true` все запросы идут на `testnet-pay.crypt.bot`. Используйте для тестирования без реальных средств.
### Webhook
Укажите в @CryptoBot -> My Apps -> Webhook: `https://hooks.domain.com/cryptobot-webhook`
***
## CloudPayments
Платежи через виджет CloudPayments с поддержкой 3D-Secure.
### Обязательные настройки
```env theme={null}
CLOUDPAYMENTS_ENABLED=true
CLOUDPAYMENTS_PUBLIC_ID=pk_xxxxxxxxxxxxx
CLOUDPAYMENTS_API_SECRET=your_api_secret
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| --------------------------------- | ------ | -------------------------------------- | ------------------------------------------ |
| `CLOUDPAYMENTS_ENABLED` | `bool` | `false` | Включить CloudPayments |
| `CLOUDPAYMENTS_PUBLIC_ID` | `str` | — | **Обязательно**. Public ID магазина |
| `CLOUDPAYMENTS_API_SECRET` | `str` | — | **Обязательно**. API Secret |
| `CLOUDPAYMENTS_DISPLAY_NAME` | `str` | `CloudPayments` | Отображаемое название |
| `CLOUDPAYMENTS_API_URL` | `str` | `https://api.cloudpayments.ru` | URL API |
| `CLOUDPAYMENTS_WIDGET_URL` | `str` | `https://widget.cloudpayments.ru/show` | URL виджета оплаты |
| `CLOUDPAYMENTS_DESCRIPTION` | `str` | `Пополнение баланса` | Описание платежа |
| `CLOUDPAYMENTS_CURRENCY` | `str` | `RUB` | Валюта |
| `CLOUDPAYMENTS_MIN_AMOUNT_KOPEKS` | `int` | `5000` | Минимальная сумма (50 руб) |
| `CLOUDPAYMENTS_MAX_AMOUNT_KOPEKS` | `int` | `10000000` | Максимальная сумма (100 000 руб) |
| `CLOUDPAYMENTS_WEBHOOK_PATH` | `str` | `/cloudpayments-webhook` | Путь webhook |
| `CLOUDPAYMENTS_WEBHOOK_HOST` | `str` | `0.0.0.0` | Хост для webhook |
| `CLOUDPAYMENTS_WEBHOOK_PORT` | `int` | `8087` | Порт (устаревший, используется 8080) |
| `CLOUDPAYMENTS_RETURN_URL` | `str` | — | URL возврата после оплаты |
| `CLOUDPAYMENTS_SKIN` | `str` | `mini` | Стиль виджета: `mini`, `classic`, `modern` |
| `CLOUDPAYMENTS_REQUIRE_EMAIL` | `bool` | `false` | Требовать email при оплате |
| `CLOUDPAYMENTS_TEST_MODE` | `bool` | `false` | Тестовый режим (без реальных списаний) |
### Webhook
CloudPayments использует несколько суб-роутов:
| Путь | Назначение |
| ---------------------- | ---------------------------------------- |
| `{WEBHOOK_PATH}` | Универсальный обработчик (рекомендуется) |
| `{WEBHOOK_PATH}/check` | Проверка перед списанием |
| `{WEBHOOK_PATH}/pay` | Успешная оплата |
| `{WEBHOOK_PATH}/fail` | Неуспешная оплата |
В кабинете CloudPayments укажите: `https://hooks.domain.com/cloudpayments-webhook`
***
## Freekassa
### Обязательные настройки
```env theme={null}
FREEKASSA_ENABLED=true
FREEKASSA_SHOP_ID=12345
FREEKASSA_API_KEY=your_api_key
FREEKASSA_SECRET_WORD_1=secret1
FREEKASSA_SECRET_WORD_2=secret2
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| ----------------------------------- | ------ | -------------------- | -------------------------------------------------------------------- |
| `FREEKASSA_ENABLED` | `bool` | `false` | Включить Freekassa |
| `FREEKASSA_SHOP_ID` | `int` | — | **Обязательно**. ID магазина |
| `FREEKASSA_API_KEY` | `str` | — | **Обязательно**. API-ключ |
| `FREEKASSA_SECRET_WORD_1` | `str` | — | **Обязательно**. Секретное слово 1 (для формы оплаты) |
| `FREEKASSA_SECRET_WORD_2` | `str` | — | **Обязательно**. Секретное слово 2 (для webhook) |
| `FREEKASSA_DISPLAY_NAME` | `str` | `Freekassa` | Отображаемое название |
| `FREEKASSA_CURRENCY` | `str` | `RUB` | Валюта |
| `FREEKASSA_MIN_AMOUNT_KOPEKS` | `int` | `10000` | Минимальная сумма (100 руб) |
| `FREEKASSA_MAX_AMOUNT_KOPEKS` | `int` | `100000000` | Максимальная сумма (1 000 000 руб) |
| `FREEKASSA_PAYMENT_TIMEOUT_SECONDS` | `int` | `3600` | Таймаут ожидания оплаты (секунды) |
| `FREEKASSA_WEBHOOK_PATH` | `str` | `/freekassa-webhook` | Путь webhook |
| `FREEKASSA_WEBHOOK_HOST` | `str` | `0.0.0.0` | Хост для webhook |
| `FREEKASSA_WEBHOOK_PORT` | `int` | `8088` | Порт (устаревший, используется 8080) |
| `FREEKASSA_PAYMENT_SYSTEM_ID` | `int` | — | Способ оплаты: `42` = обычный СБП, `44` = NSPK СБП |
| `FREEKASSA_USE_API` | `bool` | `false` | Использовать API для создания заказов |
| `SERVER_PUBLIC_IP` | `str` | — | Публичный IP сервера (для Freekassa API, определяется автоматически) |
### Режимы создания платежей
* `FREEKASSA_USE_API=false` — редирект на платёжную форму Freekassa (по умолчанию)
* `FREEKASSA_USE_API=true` — создание заказа через API (рекомендуется для NSPK СБП)
```env theme={null}
# Для NSPK СБП (QR-код, быстрее и надёжнее)
FREEKASSA_USE_API=true
FREEKASSA_PAYMENT_SYSTEM_ID=44
```
### Webhook
В кабинете Freekassa укажите: `https://hooks.domain.com/freekassa-webhook`
***
## Kassa AI
Отдельная платёжная система (`api.fk.life`), работает параллельно с Freekassa.
### Обязательные настройки
```env theme={null}
KASSA_AI_ENABLED=true
KASSA_AI_SHOP_ID=12345
KASSA_AI_API_KEY=your_api_key
KASSA_AI_SECRET_WORD_2=secret2
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| ---------------------------- | ------ | ------------------- | ------------------------------------------------------------- |
| `KASSA_AI_ENABLED` | `bool` | `false` | Включить Kassa AI |
| `KASSA_AI_SHOP_ID` | `int` | — | **Обязательно**. ID магазина |
| `KASSA_AI_API_KEY` | `str` | — | **Обязательно**. API-ключ |
| `KASSA_AI_SECRET_WORD_2` | `str` | — | **Обязательно**. Секретное слово (для webhook) |
| `KASSA_AI_DISPLAY_NAME` | `str` | `KassaAI` | Отображаемое название |
| `KASSA_AI_CURRENCY` | `str` | `RUB` | Валюта |
| `KASSA_AI_MIN_AMOUNT_KOPEKS` | `int` | `10000` | Минимальная сумма (100 руб) |
| `KASSA_AI_MAX_AMOUNT_KOPEKS` | `int` | `100000000` | Максимальная сумма (1 000 000 руб) |
| `KASSA_AI_WEBHOOK_PATH` | `str` | `/kassa-ai-webhook` | Путь webhook |
| `KASSA_AI_WEBHOOK_HOST` | `str` | `0.0.0.0` | Хост для webhook |
| `KASSA_AI_WEBHOOK_PORT` | `int` | `8089` | Порт (устаревший, используется 8080) |
| `KASSA_AI_PAYMENT_SYSTEM_ID` | `int` | `44` | Способ оплаты: `44` = СБП QR, `36` = Карты РФ, `43` = SberPay |
### Webhook
В кабинете Kassa AI укажите: `https://hooks.domain.com/kassa-ai-webhook`
***
## PayPalych (Pal24)
Платежи через PayPalych (СБП и банковские карты).
### Обязательные настройки
```env theme={null}
PAL24_ENABLED=true
PAL24_API_TOKEN=your_api_token
PAL24_SHOP_ID=your_shop_id
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| --------------------------- | ------ | --------------------------- | ------------------------------------------------ |
| `PAL24_ENABLED` | `bool` | `false` | Включить PayPalych |
| `PAL24_API_TOKEN` | `str` | — | **Обязательно**. API-токен |
| `PAL24_SHOP_ID` | `str` | — | **Обязательно**. ID магазина |
| `PAL24_DISPLAY_NAME` | `str` | `PAL24` | Отображаемое название |
| `PAL24_SIGNATURE_TOKEN` | `str` | — | Токен для проверки подписи webhook |
| `PAL24_BASE_URL` | `str` | `https://pal24.pro/api/v1/` | Базовый URL API |
| `PAL24_WEBHOOK_PATH` | `str` | `/pal24-webhook` | Путь webhook |
| `PAL24_PAYMENT_DESCRIPTION` | `str` | `Пополнение баланса` | Описание платежа |
| `PAL24_MIN_AMOUNT_KOPEKS` | `int` | `10000` | Минимальная сумма (100 руб) |
| `PAL24_MAX_AMOUNT_KOPEKS` | `int` | `100000000` | Максимальная сумма (1 000 000 руб) |
| `PAL24_REQUEST_TIMEOUT` | `int` | `30` | Таймаут запросов к API (секунды) |
| `PAL24_SBP_BUTTON_TEXT` | `str` | — | Текст кнопки СБП (по умолчанию из локализации) |
| `PAL24_CARD_BUTTON_TEXT` | `str` | — | Текст кнопки карты (по умолчанию из локализации) |
| `PAL24_SBP_BUTTON_VISIBLE` | `bool` | `true` | Показывать кнопку СБП |
| `PAL24_CARD_BUTTON_VISIBLE` | `bool` | `true` | Показывать кнопку карты |
### Webhook
В кабинете Pal24 укажите Result URL: `https://hooks.domain.com/pal24-webhook`
***
## Platega
Поддерживает несколько методов оплаты: СБП, карты, международные карты и криптовалюту.
### Обязательные настройки
```env theme={null}
PLATEGA_ENABLED=true
PLATEGA_MERCHANT_ID=your_merchant_id
PLATEGA_SECRET=your_secret_key
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| --------------------------- | ------ | ------------------------ | -------------------------------------------- |
| `PLATEGA_ENABLED` | `bool` | `false` | Включить Platega |
| `PLATEGA_MERCHANT_ID` | `str` | — | **Обязательно**. ID мерчанта |
| `PLATEGA_SECRET` | `str` | — | **Обязательно**. Секретный ключ |
| `PLATEGA_DISPLAY_NAME` | `str` | `Platega` | Отображаемое название |
| `PLATEGA_BASE_URL` | `str` | `https://app.platega.io` | Базовый URL API |
| `PLATEGA_RETURN_URL` | `str` | — | URL возврата после оплаты |
| `PLATEGA_FAILED_URL` | `str` | — | URL возврата при ошибке |
| `PLATEGA_CURRENCY` | `str` | `RUB` | Валюта |
| `PLATEGA_ACTIVE_METHODS` | `str` | `2,10,11,12,13` | Коды активных методов оплаты (через запятую) |
| `PLATEGA_MIN_AMOUNT_KOPEKS` | `int` | `10000` | Минимальная сумма (100 руб) |
| `PLATEGA_MAX_AMOUNT_KOPEKS` | `int` | `100000000` | Максимальная сумма (1 000 000 руб) |
| `PLATEGA_WEBHOOK_PATH` | `str` | `/platega-webhook` | Путь webhook |
| `PLATEGA_WEBHOOK_HOST` | `str` | `0.0.0.0` | Хост для webhook |
| `PLATEGA_WEBHOOK_PORT` | `int` | `8086` | Порт (устаревший, используется 8080) |
### Методы оплаты
Коды для `PLATEGA_ACTIVE_METHODS`:
| Код | Метод |
| ---- | ---------------------- |
| `2` | СБП (QR) |
| `10` | Банковские карты (RUB) |
| `11` | Банковские карты |
| `12` | Международные карты |
| `13` | Криптовалюта |
```env theme={null}
# Только СБП и карты RUB
PLATEGA_ACTIVE_METHODS=2,10
```
### Inline-отображение
Если у Platega настроено несколько активных методов (`PLATEGA_ACTIVE_METHODS`), каждый метод отображается как отдельная кнопка на главном экране бота. Пользователь сразу видит доступные варианты (СБП, карты, крипто) без дополнительных переходов.
### Webhook
В кабинете Platega укажите: `https://hooks.domain.com/platega-webhook`
***
## WATA
Платежи картами через WATA.
### Обязательные настройки
```env theme={null}
WATA_ENABLED=true
WATA_ACCESS_TOKEN=your_access_token
WATA_TERMINAL_PUBLIC_ID=your_terminal_id
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| ------------------------------- | ------ | ------------------------------ | -------------------------------------------- |
| `WATA_ENABLED` | `bool` | `false` | Включить WATA |
| `WATA_ACCESS_TOKEN` | `str` | — | **Обязательно**. Токен доступа |
| `WATA_TERMINAL_PUBLIC_ID` | `str` | — | **Обязательно**. Public ID терминала |
| `WATA_DISPLAY_NAME` | `str` | `Wata` | Отображаемое название |
| `WATA_BASE_URL` | `str` | `https://api.wata.pro/api/h2h` | Базовый URL API |
| `WATA_PAYMENT_DESCRIPTION` | `str` | `Пополнение баланса` | Описание платежа |
| `WATA_PAYMENT_TYPE` | `str` | `OneTime` | Тип платежа |
| `WATA_SUCCESS_REDIRECT_URL` | `str` | — | URL после успешной оплаты |
| `WATA_FAIL_REDIRECT_URL` | `str` | — | URL после ошибки |
| `WATA_LINK_TTL_MINUTES` | `int` | — | Время жизни ссылки на оплату (минуты) |
| `WATA_MIN_AMOUNT_KOPEKS` | `int` | `10000` | Минимальная сумма (100 руб) |
| `WATA_MAX_AMOUNT_KOPEKS` | `int` | `100000000` | Максимальная сумма (1 000 000 руб) |
| `WATA_REQUEST_TIMEOUT` | `int` | `30` | Таймаут запросов (секунды) |
| `WATA_WEBHOOK_PATH` | `str` | `/wata-webhook` | Путь webhook |
| `WATA_WEBHOOK_HOST` | `str` | `0.0.0.0` | Хост для webhook |
| `WATA_WEBHOOK_PORT` | `int` | `8085` | Порт (устаревший, используется 8080) |
| `WATA_PUBLIC_KEY_URL` | `str` | — | URL публичного ключа для проверки подписи |
| `WATA_PUBLIC_KEY_CACHE_SECONDS` | `int` | `3600` | Время кэширования публичного ключа (секунды) |
### Webhook
В кабинете WATA укажите: `https://hooks.domain.com/wata-webhook`
***
## Heleket
Криптовалютный провайдер с поддержкой USDT и других валют.
### Обязательные настройки
```env theme={null}
HELEKET_ENABLED=true
HELEKET_MERCHANT_ID=your_merchant_id
HELEKET_API_KEY=your_api_key
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| -------------------------- | ------- | ---------------------------- | -------------------------------------------------------------------- |
| `HELEKET_ENABLED` | `bool` | `false` | Включить Heleket |
| `HELEKET_MERCHANT_ID` | `str` | — | **Обязательно**. ID мерчанта |
| `HELEKET_API_KEY` | `str` | — | **Обязательно**. API-ключ |
| `HELEKET_DISPLAY_NAME` | `str` | `Heleket Crypto` | Отображаемое название |
| `HELEKET_BASE_URL` | `str` | `https://api.heleket.com/v1` | Базовый URL API |
| `HELEKET_DEFAULT_CURRENCY` | `str` | `USDT` | Валюта по умолчанию |
| `HELEKET_DEFAULT_NETWORK` | `str` | — | Сеть по умолчанию |
| `HELEKET_INVOICE_LIFETIME` | `int` | `3600` | Время жизни инвойса (секунды, 300-43200) |
| `HELEKET_MARKUP_PERCENT` | `float` | `0.0` | Наценка в процентах |
| `HELEKET_WEBHOOK_PATH` | `str` | `/heleket-webhook` | Путь webhook |
| `HELEKET_WEBHOOK_HOST` | `str` | `0.0.0.0` | Хост для webhook |
| `HELEKET_WEBHOOK_PORT` | `int` | `8086` | Порт (устаревший, используется 8080) |
| `HELEKET_CALLBACK_URL` | `str` | — | URL для callback (по умолчанию `WEBHOOK_URL + HELEKET_WEBHOOK_PATH`) |
| `HELEKET_RETURN_URL` | `str` | — | URL возврата после оплаты |
| `HELEKET_SUCCESS_URL` | `str` | — | URL успешной оплаты |
### Webhook
В кабинете Heleket укажите Callback URL: `https://hooks.domain.com/heleket-webhook`
***
## MulenPay
### Обязательные настройки
```env theme={null}
MULENPAY_ENABLED=true
MULENPAY_API_KEY=your_api_key
MULENPAY_SECRET_KEY=your_secret_key
MULENPAY_SHOP_ID=12345
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| --------------------------------- | ------ | ------------------------- | ------------------------------------------------------------- |
| `MULENPAY_ENABLED` | `bool` | `false` | Включить MulenPay |
| `MULENPAY_API_KEY` | `str` | — | **Обязательно**. API-ключ |
| `MULENPAY_SECRET_KEY` | `str` | — | **Обязательно**. Секретный ключ (для HMAC подписи webhook) |
| `MULENPAY_SHOP_ID` | `int` | — | **Обязательно**. ID магазина |
| `MULENPAY_DISPLAY_NAME` | `str` | `Mulen Pay` | Отображаемое название |
| `MULENPAY_BASE_URL` | `str` | `https://mulenpay.ru/api` | Базовый URL API |
| `MULENPAY_WEBHOOK_PATH` | `str` | `/mulenpay-webhook` | Путь webhook |
| `MULENPAY_DESCRIPTION` | `str` | `Пополнение баланса` | Описание платежа |
| `MULENPAY_LANGUAGE` | `str` | `ru` | Язык формы оплаты |
| `MULENPAY_VAT_CODE` | `int` | `0` | Код НДС |
| `MULENPAY_PAYMENT_SUBJECT` | `int` | `4` | Тип предмета расчёта |
| `MULENPAY_PAYMENT_MODE` | `int` | `4` | Режим расчёта |
| `MULENPAY_MIN_AMOUNT_KOPEKS` | `int` | `10000` | Минимальная сумма (100 руб) |
| `MULENPAY_MAX_AMOUNT_KOPEKS` | `int` | `10000000` | Максимальная сумма (100 000 руб) |
| `MULENPAY_IFRAME_EXPECTED_ORIGIN` | `str` | — | Ожидаемый origin iframe (для CORS, определяется из BASE\_URL) |
| `MULENPAY_WEBSITE_URL` | `str` | — | URL сайта магазина |
### Webhook
В кабинете MulenPay укажите: `https://hooks.domain.com/mulenpay-webhook`
Поддерживается проверка подписи через несколько форматов: HMAC-SHA256 (hex, base64), Bearer-токен, кастомные заголовки.
***
## Tribute
Платежи через Telegram-платформу Tribute. Поддерживает как разовые, так и рекуррентные донаты.
### Обязательные настройки
```env theme={null}
TRIBUTE_ENABLED=true
TRIBUTE_API_KEY=your_api_key
TRIBUTE_DONATE_LINK=https://tribute.ru/your_link
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| ---------------------- | ------ | ------------------ | ------------------------------------------------ |
| `TRIBUTE_ENABLED` | `bool` | `false` | Включить Tribute |
| `TRIBUTE_API_KEY` | `str` | — | **Обязательно**. API-ключ (для проверки webhook) |
| `TRIBUTE_DONATE_LINK` | `str` | — | Ссылка на страницу доната |
| `TRIBUTE_WEBHOOK_PATH` | `str` | `/tribute-webhook` | Путь webhook |
| `TRIBUTE_WEBHOOK_HOST` | `str` | `0.0.0.0` | Хост для webhook |
| `TRIBUTE_WEBHOOK_PORT` | `int` | `8081` | Порт (устаревший, используется 8080) |
### Особенности
* Обрабатывает события `new_donation` и `recurrent_donation`
* Поддерживает возврат средств (refund) через API
### Webhook
В кабинете Tribute укажите: `https://hooks.domain.com/tribute-webhook`
***
## RioPay
Платежи картами через RioPay (`api.riopay.online`).
### Обязательные настройки
```env theme={null}
RIOPAY_ENABLED=true
RIOPAY_API_TOKEN=your_api_token
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| -------------------------- | ------ | ----------------- | ------------------------------------------------------------------ |
| `RIOPAY_ENABLED` | `bool` | `false` | Включить RioPay |
| `RIOPAY_API_TOKEN` | `str` | — | **Обязательно**. API-токен (заголовок `x-api-token`) |
| `RIOPAY_WEBHOOK_SECRET` | `str` | — | Ключ для HMAC-SHA512 проверки webhook (по умолчанию = `API_TOKEN`) |
| `RIOPAY_DISPLAY_NAME` | `str` | `RioPay` | Отображаемое название |
| `RIOPAY_CURRENCY` | `str` | `RUB` | Валюта |
| `RIOPAY_MIN_AMOUNT_KOPEKS` | `int` | `10000` | Минимальная сумма (100 руб) |
| `RIOPAY_MAX_AMOUNT_KOPEKS` | `int` | `100000000` | Максимальная сумма (1 000 000 руб) |
| `RIOPAY_WEBHOOK_PATH` | `str` | `/riopay-webhook` | Путь webhook |
| `RIOPAY_SUCCESS_URL` | `str` | — | URL после успешной оплаты |
| `RIOPAY_FAIL_URL` | `str` | — | URL после ошибки |
### Webhook
В кабинете RioPay укажите: `https://hooks.domain.com/riopay-webhook`
Подпись webhook проверяется через HMAC-SHA512 (заголовок `X-Signature`). Если `RIOPAY_WEBHOOK_SECRET` не указан, используется значение `RIOPAY_API_TOKEN`.
***
## SeverPay
Платежи через SeverPay (СБП и банковские карты) с HMAC-SHA256 подписью webhook.
### Обязательные настройки
```env theme={null}
SEVERPAY_ENABLED=true
SEVERPAY_MID=12345
SEVERPAY_TOKEN=your_secret_token
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| ---------------------------- | ------ | ------------------- | ------------------------------------------------------ |
| `SEVERPAY_ENABLED` | `bool` | `false` | Включить SeverPay |
| `SEVERPAY_MID` | `int` | — | **Обязательно**. Merchant ID |
| `SEVERPAY_TOKEN` | `str` | — | **Обязательно**. Секретный токен (HMAC-SHA256 подпись) |
| `SEVERPAY_DISPLAY_NAME` | `str` | `SeverPay` | Отображаемое название |
| `SEVERPAY_CURRENCY` | `str` | `RUB` | Валюта |
| `SEVERPAY_MIN_AMOUNT_KOPEKS` | `int` | `10000` | Минимальная сумма (100 руб) |
| `SEVERPAY_MAX_AMOUNT_KOPEKS` | `int` | `10000000` | Максимальная сумма (100 000 руб) |
| `SEVERPAY_WEBHOOK_PATH` | `str` | `/severpay-webhook` | Путь webhook |
| `SEVERPAY_RETURN_URL` | `str` | — | URL возврата после оплаты |
| `SEVERPAY_LIFETIME` | `int` | `1440` | Время жизни платежа (минуты, 30–4320) |
### Webhook
В кабинете SeverPay укажите: `https://hooks.domain.com/severpay-webhook`
Подпись webhook проверяется через HMAC-SHA256. Webhook всегда возвращает HTTP 200 для предотвращения повторных запросов от SeverPay.
***
## PayPear
Платежи через PayPear (`api.paypear.ru`) с поддержкой банковских карт, СБП, SberPay и T-Pay. Аутентификация через HTTP Basic Auth, идемпотентность через UUID.
### Обязательные настройки
```env theme={null}
PAYPEAR_ENABLED=true
PAYPEAR_SHOP_ID=your_shop_id
PAYPEAR_SECRET_KEY=your_secret_key
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| ---------------------------------- | ------ | ------------------ | ------------------------------------------------ |
| `PAYPEAR_ENABLED` | `bool` | `false` | Включить PayPear |
| `PAYPEAR_SHOP_ID` | `str` | — | **Обязательно**. ID магазина (для Basic Auth) |
| `PAYPEAR_SECRET_KEY` | `str` | — | **Обязательно**. Секретный ключ (для Basic Auth) |
| `PAYPEAR_DISPLAY_NAME` | `str` | `PayPear` | Отображаемое название |
| `PAYPEAR_CURRENCY` | `str` | `RUB` | Валюта |
| `PAYPEAR_MIN_AMOUNT_KOPEKS` | `int` | `10000` | Минимальная сумма (100 руб) |
| `PAYPEAR_MAX_AMOUNT_KOPEKS` | `int` | `10000000` | Максимальная сумма (100 000 руб) |
| `PAYPEAR_WEBHOOK_PATH` | `str` | `/paypear-webhook` | Путь webhook |
| `PAYPEAR_RETURN_URL` | `str` | — | URL возврата после оплаты |
| `PAYPEAR_PAYMENT_LIFETIME_MINUTES` | `int` | `60` | Время жизни платежа (минуты) |
### Методы оплаты
PayPear поддерживает 4 метода оплаты, доступных как sub-options в кабинете:
* **bank\_card** — банковские карты (Visa, Mastercard, Мир)
* **sbp** — Система быстрых платежей
* **sberpay** — SberPay (через приложение СберБанк Онлайн)
* **tpay** — T-Pay (через приложение Т-Банка)
### Webhook
В личном кабинете PayPear укажите: `https://hooks.domain.com/paypear-webhook`
Webhook содержит поле `signature` в теле запроса (HMAC-SHA256). Поддерживаемые события: `payment.confirmed`, `payment.canceled`. PayPear повторяет отправку в течение 24 часов при получении не-200 ответа.
### Статусы платежей
| Статус | Описание |
| ----------- | ------------------------- |
| `NEW` | Создан, ожидает оплаты |
| `PROCESS` | Клиент инициировал оплату |
| `CONFIRMED` | Оплачен (финальный) |
| `CANCELED` | Отменён (финальный) |
| `REFUNDED` | Возвращён (финальный) |
| `EXPIRED` | Истёк срок (финальный) |
***
## RollyPay
Платежи через RollyPay (`rollypay.io`) — платёжный шлюз с приёмом рублей и автоматической конвертацией в USDT. Поддержка СБП, карт и криптовалюты.
### Обязательные настройки
```env theme={null}
ROLLYPAY_ENABLED=true
ROLLYPAY_API_KEY=rpk_live_your_api_key
ROLLYPAY_SIGNING_SECRET=your_signing_secret
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| ---------------------------- | ------ | ------------------- | ----------------------------------------------------- |
| `ROLLYPAY_ENABLED` | `bool` | `false` | Включить RollyPay |
| `ROLLYPAY_API_KEY` | `str` | — | **Обязательно**. API ключ (header X-API-Key) |
| `ROLLYPAY_SIGNING_SECRET` | `str` | — | **Обязательно**. Секрет для HMAC верификации вебхуков |
| `ROLLYPAY_DISPLAY_NAME` | `str` | `RollyPay` | Отображаемое название |
| `ROLLYPAY_CURRENCY` | `str` | `RUB` | Валюта |
| `ROLLYPAY_MIN_AMOUNT_KOPEKS` | `int` | `10000` | Минимальная сумма (100 руб) |
| `ROLLYPAY_MAX_AMOUNT_KOPEKS` | `int` | `10000000` | Максимальная сумма (100 000 руб) |
| `ROLLYPAY_WEBHOOK_PATH` | `str` | `/rollypay-webhook` | Путь webhook |
| `ROLLYPAY_RETURN_URL` | `str` | — | URL возврата после оплаты |
### Методы оплаты
RollyPay поддерживает 3 метода, доступных как sub-options:
* **sbp** — Система быстрых платежей
* **card** — Банковские карты
* **crypto** — Криптовалюта
Если метод не указан, платёжная форма RollyPay покажет все доступные варианты.
### Webhook
Webhook URL настраивается при создании кассы (terminal) в RollyPay. Укажите: `https://hooks.domain.com/rollypay-webhook`
Подпись передаётся в header `X-Signature` (HMAC-SHA256 от `timestamp.body`), timestamp — в `X-Timestamp`. Повторные попытки: экспоненциальный backoff 30с×2^(n-1), максимум 8 попыток (\~2 часа).
### Особенности
* Все платежи конвертируются в USDT по текущему курсу
* Баланс кассы хранится в USDT
* Каждый запрос требует уникальный `X-Nonce` (UUID), повторное использование в течение 10 минут запрещено
* Поддерживаемые события: `payment.paid`, `payment.canceled`, `payment.chargeback`
### Статусы платежей
| Статус | Описание |
| ------------ | ----------------------------------------- |
| `created` | Создан, ожидает оплаты |
| `processing` | QR активирован, клиент инициировал оплату |
| `paid` | Оплачен (финальный) |
| `expired` | Истёк срок (финальный) |
| `canceled` | Отменён (финальный) |
| `chargeback` | Возврат после успешной оплаты |
***
## AuraPay
Платежи через AuraPay (`app.aurapay.tech`) с поддержкой банковских карт и СБП. Аутентификация через API-ключ и ID кассы в заголовках.
### Обязательные настройки
```env theme={null}
AURAPAY_ENABLED=true
AURAPAY_API_KEY=your_api_key
AURAPAY_SHOP_ID=your_shop_uuid
AURAPAY_SECRET_KEY=your_secret_key_2
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| ---------------------------------- | ------ | ------------------ | -------------------------------------------------------- |
| `AURAPAY_ENABLED` | `bool` | `false` | Включить AuraPay |
| `AURAPAY_API_KEY` | `str` | — | **Обязательно**. API ключ (header X-ApiKey) |
| `AURAPAY_SHOP_ID` | `str` | — | **Обязательно**. UUID кассы (header X-ShopId) |
| `AURAPAY_SECRET_KEY` | `str` | — | **Обязательно**. Секретный ключ #2 (HMAC-SHA256 webhook) |
| `AURAPAY_DISPLAY_NAME` | `str` | `AuraPay` | Отображаемое название |
| `AURAPAY_CURRENCY` | `str` | `RUB` | Валюта |
| `AURAPAY_MIN_AMOUNT_KOPEKS` | `int` | `10000` | Минимальная сумма (100 руб) |
| `AURAPAY_MAX_AMOUNT_KOPEKS` | `int` | `10000000` | Максимальная сумма (100 000 руб) |
| `AURAPAY_WEBHOOK_PATH` | `str` | `/aurapay-webhook` | Путь webhook |
| `AURAPAY_RETURN_URL` | `str` | — | URL возврата после оплаты |
| `AURAPAY_PAYMENT_LIFETIME_MINUTES` | `int` | `60` | Время жизни инвойса (минуты, 1–43200) |
### Методы оплаты
AuraPay поддерживает 2 метода оплаты, доступных как sub-options в кабинете:
* **card** — банковские карты
* **sbp** — Система быстрых платежей (СБП)
Если метод не указан, пользователь выбирает способ оплаты на платёжной форме AuraPay.
### Webhook
Webhook URL указывается при создании инвойса (параметр `callback_url`) или в настройках кассы. Укажите: `https://hooks.domain.com/aurapay-webhook`
Подпись передаётся в header `X-SIGNATURE`. Алгоритм: отсортировать ключи JSON по алфавиту, склеить все **значения** в одну строку, HMAC-SHA256 с секретным ключом #2.
Повторные попытки: максимум 5 раз, до получения HTTP 200.
### Статусы инвойсов
| Статус | Описание |
| --------- | ---------------------- |
| `PENDING` | Создан, ожидает оплаты |
| `PAID` | Оплачен (финальный) |
| `EXPIRED` | Истёк срок (финальный) |
***
## Overpay
Платежи через Overpay (`api.overpay.io`) с двойной аутентификацией: mTLS (клиентский P12 сертификат) + HTTP Basic Auth. Поддерживает банковские карты и СБП.
### Обязательные настройки
```env theme={null}
OVERPAY_ENABLED=true
OVERPAY_USERNAME=your_username
OVERPAY_PASSWORD=your_password
OVERPAY_PROJECT_ID=your_project_id
OVERPAY_P12_PATH=/app/certs/client.p12
OVERPAY_P12_PASSPHRASE=your_passphrase
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| --------------------------- | ------ | ------------------------ | --------------------------------------------------- |
| `OVERPAY_ENABLED` | `bool` | `false` | Включить Overpay |
| `OVERPAY_API_URL` | `str` | `https://api.overpay.io` | Базовый URL API |
| `OVERPAY_USERNAME` | `str` | — | **Обязательно**. Логин для HTTP Basic Auth |
| `OVERPAY_PASSWORD` | `str` | — | **Обязательно**. Пароль для HTTP Basic Auth |
| `OVERPAY_PROJECT_ID` | `str` | — | **Обязательно**. ID проекта |
| `OVERPAY_P12_PATH` | `str` | — | **Обязательно**. Путь к P12 клиентскому сертификату |
| `OVERPAY_P12_PASSPHRASE` | `str` | — | **Обязательно**. Пароль от P12 сертификата |
| `OVERPAY_DISPLAY_NAME` | `str` | `Overpay` | Отображаемое название |
| `OVERPAY_CURRENCY` | `str` | `RUB` | Валюта |
| `OVERPAY_MIN_AMOUNT_KOPEKS` | `int` | `10000` | Минимальная сумма (100 руб) |
| `OVERPAY_MAX_AMOUNT_KOPEKS` | `int` | `10000000` | Максимальная сумма (100 000 руб) |
| `OVERPAY_WEBHOOK_PATH` | `str` | `/overpay-webhook` | Путь webhook |
| `OVERPAY_RETURN_URL` | `str` | — | URL возврата после оплаты |
| `OVERPAY_LIFETIME_MINUTES` | `int` | `1440` | Время жизни платежа (минуты, по умолчанию 24 часа) |
| `OVERPAY_PAYMENT_METHODS` | `str` | `card,fps` | Методы оплаты (через запятую) |
### Методы оплаты
| Метод | Описание |
| ------ | ------------------------------ |
| `card` | Банковские карты |
| `fps` | СБП (Система быстрых платежей) |
### Аутентификация
Overpay использует двойную аутентификацию:
1. **mTLS** — клиентский P12 сертификат прикрепляется к каждому запросу к API. Файл сертификата должен быть доступен контейнеру по пути `OVERPAY_P12_PATH`
2. **HTTP Basic Auth** — логин и пароль передаются в заголовке `Authorization`
При использовании Docker убедитесь, что файл P12 сертификата смонтирован в контейнер. Пример: `volumes: - ./certs/client.p12:/app/certs/client.p12:ro`
### Webhook
В кабинете Overpay укажите: `https://hooks.domain.com/overpay-webhook`
***
## Etoplatezhi
Etoplatezhi — российский платёжный шлюз `paymentpage.etoplatezhi.ru` с поддержкой карт и СБП. HMAC-SHA256 подпись запросов и webhook'ов.
### Обязательные настройки
```env theme={null}
ETOPLATEZHI_ENABLED=true
ETOPLATEZHI_PROJECT_ID=12345
ETOPLATEZHI_SECRET_KEY=your_secret_key
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| -------------------------------------- | ---- | ---------------------- | ---------------------------------------- |
| `ETOPLATEZHI_ENABLED` | bool | false | Включает Etoplatezhi |
| `ETOPLATEZHI_PROJECT_ID` | int | — | **Обязательно**. ID проекта |
| `ETOPLATEZHI_SECRET_KEY` | str | — | **Обязательно**. Секретный ключ для HMAC |
| `ETOPLATEZHI_DISPLAY_NAME` | str | Etoplatezhi | Имя в кнопке |
| `ETOPLATEZHI_CURRENCY` | str | RUB | Валюта |
| `ETOPLATEZHI_MIN_AMOUNT_KOPEKS` | int | 10000 | Минимальная сумма |
| `ETOPLATEZHI_MAX_AMOUNT_KOPEKS` | int | 10000000 | Максимальная сумма |
| `ETOPLATEZHI_WEBHOOK_PATH` | str | `/etoplatezhi-webhook` | Путь webhook'а |
| `ETOPLATEZHI_RETURN_URL` | str | — | URL возврата |
| `ETOPLATEZHI_PAYMENT_LIFETIME_MINUTES` | int | 60 | Время жизни инвойса |
| `ETOPLATEZHI_SBP_ENABLED` | bool | false | Кнопка «СБП» |
| `ETOPLATEZHI_CARD_ENABLED` | bool | false | Кнопка «Карта» |
### Webhook
URL: `https://hooks.domain.com/etoplatezhi-webhook`
Подпись: HMAC-SHA256, sticky terminal-status guard защищает от replay-атак.
***
## Antilopay
Antilopay — российский эквайринг `lk.antilopay.com` через **API v2**. Использует **RSA подпись** (SHA256WithRSA, PKCS#1 v1.5) — отличается от большинства провайдеров. Поддерживает 3 sub-метода: Карта, СБП, SberPay.
### Обязательные настройки
```env theme={null}
ANTILOPAY_ENABLED=true
ANTILOPAY_SECRET_ID=your_secret_id
ANTILOPAY_PRIVATE_KEY=base64_encoded_rsa_private_key
ANTILOPAY_PUBLIC_KEY=base64_encoded_rsa_public_key
ANTILOPAY_PROJECT_ID=your_project_id
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| ------------------------------------ | ---- | -------------------- | ---------------------------------------------------------------------- |
| `ANTILOPAY_ENABLED` | bool | false | Включает Antilopay |
| `ANTILOPAY_SECRET_ID` | str | — | **Обязательно**. Secret ID из ЛК Antilopay |
| `ANTILOPAY_PRIVATE_KEY` | str | — | **Обязательно**. base64-encoded RSA private key (для подписи запросов) |
| `ANTILOPAY_PUBLIC_KEY` | str | — | **Обязательно**. base64-encoded RSA public key (для проверки webhook) |
| `ANTILOPAY_PROJECT_ID` | str | — | **Обязательно**. ID проекта |
| `ANTILOPAY_DISPLAY_NAME` | str | Antilopay | Имя в кнопке |
| `ANTILOPAY_PRODUCT_NAME` | str | VPN подписка | Название продукта в чеке |
| `ANTILOPAY_PRODUCT_TYPE` | str | services | Тип продукта (для 54-ФЗ) |
| `ANTILOPAY_CURRENCY` | str | RUB | Валюта |
| `ANTILOPAY_MIN_AMOUNT_KOPEKS` | int | 10000 | Минимальная сумма |
| `ANTILOPAY_MAX_AMOUNT_KOPEKS` | int | 10000000 | Максимальная сумма |
| `ANTILOPAY_WEBHOOK_PATH` | str | `/antilopay-webhook` | Путь webhook'а |
| `ANTILOPAY_RETURN_URL` | str | — | URL возврата |
| `ANTILOPAY_PAYMENT_LIFETIME_MINUTES` | int | 60 | Время жизни инвойса |
| `ANTILOPAY_SBP_ENABLED` | bool | false | Кнопка «СБП» |
| `ANTILOPAY_CARD_ENABLED` | bool | false | Кнопка «Карта» |
| `ANTILOPAY_SBERPAY_ENABLED` | bool | false | Кнопка «SberPay» |
### Webhook
URL: `https://hooks.domain.com/antilopay-webhook`
Подпись: SHA256WithRSA (PKCS#1 v1.5), проверяется публичным ключом. Заголовок: `X-Apay-Callback`.
Antilopay требует RSA-ключевую пару. Сгенерируйте 2048-битный ключ через `openssl genrsa` и base64-кодируйте оба ключа. Публичный ключ загрузите в кабинет Antilopay.
***
## Jupiter (FPGate P2P)
Jupiter — платёжный шлюз `app.juppiter.tech` по спеке **FPGate P2P v2.1**. Эквайринг СБП через QR-код банковского приложения. HMAC-SHA256 подпись. Bedolaga — официальный партнёр Jupiter (подключение по кодовому слову `БЕДОЛАГА`).
### Обязательные настройки
```env theme={null}
JUPITER_ENABLED=true
JUPITER_TOKEN=your_token
JUPITER_SECRET=your_secret
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| ---------------------------------- | ---- | ------------------------------------------------------ | -------------------------------------------------- |
| `JUPITER_ENABLED` | bool | false | Включает Jupiter |
| `JUPITER_TOKEN` | str | — | **Обязательно**. Токен из ЛК Jupiter |
| `JUPITER_SECRET` | str | — | **Обязательно**. Секретный ключ для HMAC |
| `JUPITER_BASE_URL` | str | [https://app.juppiter.tech](https://app.juppiter.tech) | URL API |
| `JUPITER_METHOD_ID` | str | — | Опционально. ID метода (если требуется) |
| `JUPITER_METHOD_DESCRIPTION` | str | SBP | Описание метода в payload |
| `JUPITER_DISPLAY_NAME` | str | Jupiter | Имя в кнопке |
| `JUPITER_CURRENCY` | str | RUB | Валюта |
| `JUPITER_MIN_AMOUNT_KOPEKS` | int | 10000 | Минимальная сумма |
| `JUPITER_MAX_AMOUNT_KOPEKS` | int | 10000000 | Максимальная сумма |
| `JUPITER_WEBHOOK_PATH` | str | `/jupiter-webhook` | Путь webhook'а |
| `JUPITER_RETURN_URL` | str | — | URL возврата |
| `JUPITER_PAYMENT_LIFETIME_MINUTES` | int | 60 | Время жизни инвойса |
| `JUPITER_FALLBACK_EMAIL` | str | [user@vpn.bot](mailto:user@vpn.bot) | Email для customer (если у пользователя нет email) |
| `JUPITER_FALLBACK_PHONE` | str | 0000000000 | Phone-fallback |
| `JUPITER_FALLBACK_NAME` | str | User | Name-fallback |
| `JUPITER_SBP_ENABLED` | bool | false | Кнопка «СБП» |
### API Endpoints
* `POST /api/v2.1/p2p_payin` — создание инвойса
* `POST /api/v2.1/p2p_status` — статус инвойса
* `POST /api/v2.1/p2p_balance` — баланс мерчанта
### Webhook
URL: `https://hooks.domain.com/jupiter-webhook`
Подпись: HMAC-SHA256 от raw JSON body, поле `signature` в payload.
Sticky terminal-status guard — повторный success после `cancelled`/`error` логируется как `ERROR`.
📩 Менеджер: [@k\_juppiter](https://t.me/k_juppiter)
***
## Donut (Donut P2P)
Donut — платёжная система `gw.donut.business` по спеке **Donut P2P**. P2P-оплата картой, СБП по номеру телефона и СБП QR. HMAC-SHA256 подпись. Bedolaga — официальный партнёр Donut.
### Обязательные настройки
```env theme={null}
DONUT_ENABLED=true
DONUT_TOKEN=your_token
DONUT_SECRET=your_secret
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| -------------------------------- | ---- | ------------------------------------------------------ | ------------------------------------------ |
| `DONUT_ENABLED` | bool | false | Включает Donut |
| `DONUT_TOKEN` | str | — | **Обязательно**. Токен из ЛК Donut |
| `DONUT_SECRET` | str | — | **Обязательно**. Секретный ключ для HMAC |
| `DONUT_BASE_URL` | str | [https://gw.donut.business](https://gw.donut.business) | URL API |
| `DONUT_METHOD_ID` | str | — | Опционально. ID метода (если требуется) |
| `DONUT_DISPLAY_NAME` | str | Donut | Имя в кнопке |
| `DONUT_CURRENCY` | str | RUB | Валюта |
| `DONUT_MIN_AMOUNT_KOPEKS` | int | 10000 | Минимальная сумма |
| `DONUT_MAX_AMOUNT_KOPEKS` | int | 10000000 | Максимальная сумма |
| `DONUT_WEBHOOK_PATH` | str | `/donut-webhook` | Путь webhook'а |
| `DONUT_RETURN_URL` | str | — | URL возврата |
| `DONUT_PAYMENT_LIFETIME_MINUTES` | int | 60 | Время жизни инвойса |
| `DONUT_CARD_ENABLED` | bool | false | Кнопка «Карта» (description=CARD) |
| `DONUT_SBP_ENABLED` | bool | false | Кнопка «СБП» по телефону (description=SBP) |
| `DONUT_SBP_QR_ENABLED` | bool | false | Кнопка «СБП QR» (description=SBP\_QR) |
### API Endpoints
* `POST /p2p_payin` — создание инвойса
* `POST /p2p_status` — статус инвойса
* `POST /p2p_balance` — баланс мерчанта
### Webhook
URL: `https://hooks.domain.com/donut-webhook`
Подпись: HMAC-SHA256 от raw JSON body, поле `signature` в payload.
Sticky terminal-status guard защищает от replay-атак.
📩 Менеджер: [@donut\_payment](https://t.me/donut_payment)
***
## Lava Business
Lava — российский эквайринг `gate.lava.ru` (Lava Business API). Поддержка карт и СБП через `includeService` фильтрацию. HMAC-SHA256 подпись. **Раздельные ключи** для запросов и webhook'ов.
### Обязательные настройки
```env theme={null}
LAVA_ENABLED=true
LAVA_SHOP_ID=11111111-2222-3333-4444-555555555555
LAVA_SECRET_KEY=your_secret_key # для подписи запросов
LAVA_WEBHOOK_SECRET=your_secret_key_2 # для проверки webhook
```
### Все переменные
| Переменная | Тип | По умолчанию | Описание |
| ------------------------------- | ---- | -------------------------------------------- | ---------------------------------------------------- |
| `LAVA_ENABLED` | bool | false | Включает Lava |
| `LAVA_SHOP_ID` | uuid | — | **Обязательно**. UUID проекта |
| `LAVA_SECRET_KEY` | str | — | **Обязательно**. Secret\_key для HMAC запросов |
| `LAVA_WEBHOOK_SECRET` | str | — | **Обязательно**. Secret\_key\_2 для проверки webhook |
| `LAVA_BASE_URL` | str | [https://gate.lava.ru](https://gate.lava.ru) | URL API |
| `LAVA_DISPLAY_NAME` | str | Lava | Имя в кнопке |
| `LAVA_CURRENCY` | str | RUB | Валюта |
| `LAVA_MIN_AMOUNT_KOPEKS` | int | 10000 | Минимальная сумма |
| `LAVA_MAX_AMOUNT_KOPEKS` | int | 10000000 | Максимальная сумма |
| `LAVA_WEBHOOK_PATH` | str | `/lava-webhook` | Путь webhook'а |
| `LAVA_RETURN_URL` | str | — | URL возврата |
| `LAVA_PAYMENT_LIFETIME_MINUTES` | int | 60 | Время жизни инвойса (clamp до 7200, макс 5 дней) |
| `LAVA_CARD_ENABLED` | bool | false | Кнопка «Карта» (`includeService=['card']`) |
| `LAVA_SBP_ENABLED` | bool | false | Кнопка «СБП» (`includeService=['sbp']`) |
### API Endpoints
* `POST /api/v2/invoice/create` — создание инвойса
* `POST /api/v2/invoice/status` — статус инвойса
* `POST /api/v2/invoice/services` — доступные методы оплаты для shopId
### Webhook
URL: `https://hooks.domain.com/lava-webhook`
Подпись: HMAC-SHA256 от **raw bytes** (не decoded string!), заголовок `Authorization`.
В отличие от других провайдеров, Lava имеет **два секретных ключа**: `secret_key` для подписи запросов и `secret_key_2` для проверки webhook. Оба генерируются в личном кабинете Lava.
Lava ретраит webhook до 5 раз каждые 150 секунд при HTTP не-200. Бот всегда отдаёт 200 после успешной верификации подписи.
***
## Apple In-App Purchase
Apple IAP — нативные **consumable**-покупки (пополнения баланса) через iOS App Store Mini App. Используется **App Store Server API** с JWT-аутентификацией (ES256, .p8 ключ) и **App Store Server Notifications V2** для real-time событий (purchase, refund, revoke). Поддерживает Sandbox + Production окружения, refund handling с защитой от double-deduction, idempotency на уровне `web_order_line_item_id`, self-healing через reconciliation service.
### Минимальная конфигурация
```env theme={null}
APPLE_IAP_ENABLED=true
APPLE_IAP_BUNDLE_ID=com.example.vpnclient
APPLE_IAP_ISSUER_ID=57246542-96fe-1a63-e053-0824d011072a
APPLE_IAP_KEY_ID=2X9R4HXF34
APPLE_IAP_APP_APPLE_ID=1234567890
APPLE_IAP_PRIVATE_KEY_PATH=/run/secrets/apple/AuthKey_2X9R4HXF34.p8
APPLE_IAP_ENVIRONMENT=Production
APPLE_IAP_ROOT_CERTS_PATHS=/certs/AppleIncRootCertificate.cer,/certs/AppleRootCA-G2.cer,/certs/AppleRootCA-G3.cer
APPLE_IAP_PRODUCTS={"com.example.vpnclient.topup.100":10000,"com.example.vpnclient.topup.300":30000,"com.example.vpnclient.topup.500":50000}
```
### Все переменные
#### Ключевые (App Store Connect)
| Переменная | Тип | По умолчанию | Описание |
| ------------------------ | ---- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPLE_IAP_ENABLED` | bool | false | Включает Apple IAP. Ставьте `true` только после того как заполнены все обязательные поля ниже |
| `APPLE_IAP_BUNDLE_ID` | str | `com.app.client` | **Обязательно**. Должен **точно** совпадать с bundle ID iOS-приложения и `bundleId` в signed transactions от Apple |
| `APPLE_IAP_ISSUER_ID` | str | — | **Обязательно**. Issuer ID (UUID) из App Store Connect → Users and Access → Integrations → App Store Connect API |
| `APPLE_IAP_KEY_ID` | str | — | **Обязательно**. Key ID In-App Purchase ключа из App Store Connect (пример: `ABC123DEFG`) |
| `APPLE_IAP_APP_APPLE_ID` | int | — | **Обязательно для Production**. Числовой App Apple ID из App Store Connect, используется `SignedDataVerifier` Apple. Опционально для Sandbox |
#### Приватный ключ (.p8)
Нужна **одна из двух** опций:
| Переменная | Тип | По умолчанию | Описание |
| ---------------------------- | --- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `APPLE_IAP_PRIVATE_KEY_PATH` | str | — | **Рекомендуется для прода**. Путь к смонтированному `.p8` файлу. Пример: `/run/secrets/apple/AuthKey_ABC123DEFG.p8` |
| `APPLE_IAP_PRIVATE_KEY` | str | — | Альтернатива — содержимое `.p8` инлайн (с `\n` для переносов строк). Не рекомендуется для прода — секрет попадает в env-листинги |
#### Окружение и webhook
| Переменная | Тип | По умолчанию | Описание |
| --------------------------------------- | ---- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPLE_IAP_ENVIRONMENT` | str | `Production` | **Обязательно**. Допустимые значения: `Sandbox`, `Production`. Покупки из TestFlight приходят как Sandbox-транзакции |
| `APPLE_IAP_WEBHOOK_PATH` | str | `/apple-iap-webhook` | Путь для App Store Server Notifications V2. Полный URL для регистрации в App Store Connect: `https://your-domain.example` + этот path |
| `APPLE_IAP_ALLOW_SANDBOX_ON_PRODUCTION` | bool | false | Разрешает Production-бэкенду верифицировать Sandbox-транзакции из App Review / TestFlight. Такие транзакции **записываются для аудита, но не зачисляются на баланс** |
#### Проверка подписей и сертификаты
| Переменная | Тип | По умолчанию | Описание |
| ------------------------------------- | ---- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPLE_IAP_ROOT_CERTS_PATHS` | str | — | **Обязательно**. Comma-separated пути к Apple Root CA сертификатам (`.cer`) с [apple.com/certificateauthority](https://www.apple.com/certificateauthority/). Рекомендуемые: `Apple Inc. Root`, `Apple Root CA - G2 Root`, `Apple Root CA - G3 Root` |
| `APPLE_IAP_ENABLE_ONLINE_CERT_CHECKS` | bool | true | Включает online certificate status checks при верификации JWS. Рекомендуется `true` в проде, требует исходящий доступ к Apple CA |
#### Маппинг продуктов
| Переменная | Тип | По умолчанию | Описание |
| -------------------- | ---- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPLE_IAP_PRODUCTS` | json | — | **Обязательно**. JSON-объект: `{"product_id": kopeks_to_credit}`. Бэкенд **игнорирует** цену и amount от клиента — зачисляет ровно столько, сколько указано здесь. Это защита от подмены цены через mod'нутый клиент |
Пример с топапами 100 / 300 / 500 / 1000 ₽:
```env theme={null}
APPLE_IAP_PRODUCTS={"com.example.topup.100":10000,"com.example.topup.300":30000,"com.example.topup.500":50000,"com.example.topup.1000":100000}
```
#### Защита от abuse
| Переменная | Тип | По умолчанию | Описание |
| ------------------------------------------- | ---- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPLE_IAP_PURCHASE_RATE_LIMIT_PER_MINUTE` | int | 10 | Лимит попыток верификации покупки per-user и per-IP в минуту |
| `APPLE_IAP_PURCHASE_FAILURE_LIMIT_PER_HOUR` | int | 20 | Лимит **неудачных** верификаций per-user в час |
| `APPLE_IAP_RATE_LIMIT_FAIL_OPEN` | bool | false | При `false` (рекомендуется) — недоступность Redis блокирует endpoint целиком (fail-closed). При `true` — пропускает запросы при сбое Redis (availability > security) |
### Refund и revocation handling
При получении Apple Server Notification (`REFUND`, `REVOKE`, `REFUND_REVERSED`):
1. Notification сохраняется в `apple_notifications` со статусом `received` (для дедупликации по `payload_hash`)
2. Транзакция блокируется через `SELECT FOR UPDATE` на `apple_transactions` row
3. Списание / возврат списания применяется к балансу пользователя
4. Транзакция помечается `revoked` / `refund_reversed` с датой
5. **Idempotency:** повторный webhook с тем же `payload_hash` игнорируется
6. Если бэкенд был offline и webhook потерян — **reconciliation service** в фоне сверит состояние с App Store Server API и применит изменение
### Reconciliation service
Фоновая таска проходит по `apple_notifications` со статусом `failed` (сетевые ошибки, race с user-запросом), запрашивает текущий статус через `getTransactionInfo`, выравнивает локальное состояние с Apple. Self-healing для пропущенных webhook'ов.
### Idempotency
* **`web_order_line_item_id`** — уникальный per billing-cycle идентификатор от Apple, `UNIQUE` constraint в БД (миграция `0076`). Защищает от повторного зачисления одной и той же покупки
* **`payload_hash` нотификаций** — SHA256 от signed payload, тоже `UNIQUE`. Дедуп Apple webhook'ов
* **`app_account_token`** — UUID, который мы передаём Apple через `appAccountToken` параметр при инициации покупки в iOS-приложении. Apple возвращает его в transaction, мы матчим purchase к нашему юзеру без передачи telegram\_id / email на сторону Apple
### Создание App Store Connect API ключа
1. **App Store Connect** → Users and Access → Integrations → **App Store Connect API**
2. Выберите вкладку **In-App Purchase** (не General!)
3. Нажмите **+** → Name → **Generate**
4. Скачайте `.p8` файл (доступен **только один раз**, потом — генерация заново)
5. Скопируйте **Issuer ID** (сверху страницы) и **Key ID** (рядом с ключом)
6. Положите `.p8` файл в безопасное место и пропишите путь в `APPLE_IAP_PRIVATE_KEY_PATH`
### Регистрация webhook в App Store Connect
1. **App Store Connect** → ваше приложение → App Information → App Store Server Notifications
2. **Production URL:** `https://your-domain.example` + `APPLE_IAP_WEBHOOK_PATH`
3. **Sandbox URL:** тот же путь, но на тестовом доменe (если есть отдельный)
4. **Version:** Version 2 Notifications (Version 1 не поддерживается)
Apple IAP отображается **только в Mini App на iOS**. На Android и веб-кабинете кнопка не появляется, потому что Apple Review Guidelines 3.1.1 запрещают принимать платежи за digital goods вне IAP только в iOS-приложениях.
* Bundle ID в `APPLE_IAP_BUNDLE_ID` должен **точно** совпадать с реальным iOS-приложением — иначе все signed transactions будут отклонены проверкой `bundleId`
* **Никогда** не зачисляйте цену, переданную клиентом — только из `APPLE_IAP_PRODUCTS`. Клиент можно подменить
* Сертификаты Apple Root CA из `APPLE_IAP_ROOT_CERTS_PATHS` — это основа security. Без них JWS-подписи не проверяются и backend будет принимать любые поддельные транзакции
Для тестов используйте **Sandbox**-окружение с sandbox Apple ID. TestFlight-покупки тоже идут через Sandbox даже если приложение в проде.
***
## Безопасность webhook
Все платёжные webhook проходят проверку подлинности:
| Провайдер | Метод проверки |
| ------------- | ------------------------------------------------------------------------- |
| YooKassa | IP-адреса + trusted proxy networks |
| CloudPayments | HMAC-SHA256 подпись (обязательна при настроенном `API_SECRET`) |
| CryptoBot | HMAC-SHA256 подпись |
| Heleket | HMAC-SHA256 подпись |
| Freekassa | Подпись по секретному слову |
| Kassa AI | Подпись по секретному слову |
| MulenPay | HMAC-SHA256 (hex/base64/bearer) |
| Platega | HMAC-SHA256 (timing-safe comparison) |
| WATA | RSA-подпись с публичным ключом |
| Pal24 | Подпись токена + верификация суммы платежа |
| Tribute | API-ключ |
| RioPay | HMAC-SHA512 |
| SeverPay | HMAC-SHA256 |
| PayPear | HMAC-SHA256 (подпись в теле запроса) |
| RollyPay | HMAC-SHA256 (X-Signature + X-Timestamp headers) |
| AuraPay | HMAC-SHA256 (X-SIGNATURE header, sorted values) |
| Overpay | mTLS (P12 сертификат) + HTTP Basic Auth |
| Etoplatezhi | HMAC-SHA256 (sticky terminal-status guard) |
| Antilopay | RSA-подпись с публичным ключом (PKCS#1 v1.5), заголовок `X-Apay-Callback` |
| Jupiter | HMAC-SHA256 + sticky terminal-status guard |
| Donut | HMAC-SHA256 + sticky terminal-status guard |
| Lava | HMAC-SHA256 от raw bytes (`secret_key_2`), заголовок `Authorization` |
| Apple IAP | JWS подпись (App Store Server API) + bundle\_id validation |
Если для провайдера настроен секретный ключ, webhook **без подписи будут отклонены**. Убедитесь, что секретные ключи в `.env` совпадают с настройками в кабинете провайдера.
### Тестовые платежи
CloudPayments и YooKassa проверяют флаг `test_mode` в webhook. В production-окружении тестовые платежи **автоматически отклоняются**, если соответствующий `*_TEST_MODE` не включён явно.
***
## Активация провайдера
Каждый провайдер считается **включённым** только при выполнении двух условий:
1. Флаг `*_ENABLED=true`
2. Заполнены все **обязательные** поля (ключи, токены, ID)
Если включить флаг, но не заполнить обязательные поля, провайдер **не активируется** и не появится в списке способов оплаты.
| Провайдер | Условия активации |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Telegram Stars | `TELEGRAM_STARS_ENABLED=true` (включён по умолчанию) |
| YooKassa | `YOOKASSA_ENABLED` + `SHOP_ID` + `SECRET_KEY` |
| CryptoBot | `CRYPTOBOT_ENABLED` + `API_TOKEN` |
| CloudPayments | `CLOUDPAYMENTS_ENABLED` + `PUBLIC_ID` + `API_SECRET` |
| Freekassa | `FREEKASSA_ENABLED` + `SHOP_ID` + `API_KEY` + `SECRET_WORD_1` + `SECRET_WORD_2` |
| Kassa AI | `KASSA_AI_ENABLED` + `SHOP_ID` + `API_KEY` + `SECRET_WORD_2` |
| PayPalych | `PAL24_ENABLED` + `API_TOKEN` + `SHOP_ID` |
| Platega | `PLATEGA_ENABLED` + `MERCHANT_ID` + `SECRET` |
| WATA | `WATA_ENABLED` + `ACCESS_TOKEN` + `TERMINAL_PUBLIC_ID` |
| Heleket | `HELEKET_ENABLED` + `MERCHANT_ID` + `API_KEY` |
| MulenPay | `MULENPAY_ENABLED` + `API_KEY` + `SECRET_KEY` + `SHOP_ID` |
| Tribute | `TRIBUTE_ENABLED` (проверяется только флаг) |
| RioPay | `RIOPAY_ENABLED` + `API_TOKEN` |
| SeverPay | `SEVERPAY_ENABLED` + `MID` + `TOKEN` |
| Overpay | `OVERPAY_ENABLED` + `USERNAME` + `PASSWORD` + `PROJECT_ID` + `P12_PATH` + `P12_PASSPHRASE` |
| Etoplatezhi | `ETOPLATEZHI_ENABLED` + `PROJECT_ID` + `SECRET_KEY` |
| Antilopay | `ANTILOPAY_ENABLED` + `SECRET_ID` + `PRIVATE_KEY` + `PUBLIC_KEY` + `PROJECT_ID` |
| Jupiter | `JUPITER_ENABLED` + `TOKEN` + `SECRET` |
| Donut | `DONUT_ENABLED` + `TOKEN` + `SECRET` |
| Lava | `LAVA_ENABLED` + `SHOP_ID` + `SECRET_KEY` + `WEBHOOK_SECRET` |
| Apple IAP | `APPLE_IAP_ENABLED` + `BUNDLE_ID` + `ISSUER_ID` + `KEY_ID` + `APP_APPLE_ID` (для Production) + (`PRIVATE_KEY` или `PRIVATE_KEY_PATH`) + `ENVIRONMENT` + `ROOT_CERTS_PATHS` + `PRODUCTS` |
***
## Health-check
Для проверки состояния webhook доступен эндпоинт:
```
GET /health/payment-webhooks
```
Возвращает JSON со статусом каждого провайдера:
```json theme={null}
{
"status": "ok",
"tribute_enabled": false,
"mulenpay_enabled": false,
"cryptobot_enabled": true,
"yookassa_enabled": true,
"wata_enabled": false,
"heleket_enabled": false,
"pal24_enabled": false,
"platega_enabled": false,
"cloudpayments_enabled": false,
"freekassa_enabled": false,
"kassa_ai_enabled": false,
"riopay_enabled": false,
"severpay_enabled": false
}
```
***
## Настройка webhook через reverse proxy
Все webhook обрабатываются единым FastAPI-сервером на порту `8080`. Рекомендуемая настройка через Caddy/Nginx:
```
hooks.domain.com {
reverse_proxy bot:8080
}
```
В `.env` укажите:
```env theme={null}
WEBHOOK_URL=https://hooks.domain.com
```
Этот URL используется для формирования callback URL (Heleket, Platega) и return URL (YooKassa, CloudPayments).