Настройка платежей

Подключение платёжных систем, настройки баланса, автооплаты и 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.

---

Общие настройки платежей

Эти переменные влияют на все платёжные системы.

Описания и шаблоны платежей

# Название сервиса в описании платежа
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 коп вверх)

Автопроверка платежей

# Автоматическая проверка статуса незавершённых платежей (YooKassa)
PAYMENT_VERIFICATION_AUTO_CHECK_ENABLED=false
PAYMENT_VERIFICATION_AUTO_CHECK_INTERVAL_MINUTES=10

Автопокупка после пополнения

# Автоматически оформить подписку из сохранённой корзины после пополнения баланса
AUTO_PURCHASE_AFTER_TOPUP_ENABLED=false

Подробнее — см. Автопокупка и корзина.

Автооплата (автопродление)

Подробнее — см. Рекуррентные платежи.

Переменная	Тип	По умолчанию	Описание
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.

Обязательные настройки

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 поддерживает сохранение банковских карт для автоматического пополнения баланса при продлении подписки. Подробнее — см. Рекуррентные платежи.

Переменная	Тип	По умолчанию	Описание
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 (для самозанятых):

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.

Обязательные настройки

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	Время жизни инвойса (часы)

Тестовый режим

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.

Обязательные настройки

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

Обязательные настройки

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 СБП)

# Для 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.

Обязательные настройки

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 (СБП и банковские карты).

Обязательные настройки

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

Поддерживает несколько методов оплаты: СБП, карты, международные карты и криптовалюту.

Обязательные настройки

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	Криптовалюта

# Только СБП и карты RUB
PLATEGA_ACTIVE_METHODS=2,10

Inline-отображение

Если у Platega настроено несколько активных методов (PLATEGA_ACTIVE_METHODS), каждый метод отображается как отдельная кнопка на главном экране бота. Пользователь сразу видит доступные варианты (СБП, карты, крипто) без дополнительных переходов.

Webhook

В кабинете Platega укажите: https://hooks.domain.com/platega-webhook

---

WATA

Платежи картами через WATA.

Обязательные настройки

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 и других валют.

Обязательные настройки

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

Обязательные настройки

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. Поддерживает как разовые, так и рекуррентные донаты.

Обязательные настройки

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).

Обязательные настройки

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.

Обязательные настройки

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.

Обязательные настройки

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. Поддержка СБП, карт и криптовалюты.

Обязательные настройки

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 кассы в заголовках.

Обязательные настройки

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. Поддерживает банковские карты и СБП.

Обязательные настройки

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’ов.

Обязательные настройки

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.

Обязательные настройки

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 (подключение по кодовому слову БЕДОЛАГА).

Обязательные настройки

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	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	[e-mail]	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

---

Donut (Donut P2P)

Donut — платёжная система gw.donut.business по спеке Donut P2P. P2P-оплата картой, СБП по номеру телефона и СБП QR. HMAC-SHA256 подпись. Bedolaga — официальный партнёр Donut.

Обязательные настройки

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	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

---

Lava Business

Lava — российский эквайринг gate.lava.ru (Lava Business API). Поддержка карт и СБП через includeService фильтрацию. HMAC-SHA256 подпись. Раздельные ключи для запросов и webhook’ов.

Обязательные настройки

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	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.

Минимальная конфигурация

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. Рекомендуемые: 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 ₽:

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 со статусом каждого провайдера:

{
  "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 укажите:

WEBHOOK_URL=https://hooks.domain.com

Этот URL используется для формирования callback URL (Heleket, Platega) и return URL (YooKassa, CloudPayments).