💳 Интеграция платежных систем

ForgePAY поддерживает 7 платежных провайдеров для максимального удобства ваших пользователей: криптовалютные платежи, банковские карты, Telegram Stars и встроенные системы лояльности.

📌 Важно: Все конфигурационные параметры устанавливаются через переменные окружения в файле .env или конфигурационные YAML-файлы. Используйте файл .env.example как шаблон.

🎯 Обзор поддерживаемых платежных систем

Система Тип Регион Особенности
🪙 CryptoBot Криптовалюта Международная BTC, ETH, USDT, TON
💎 CrystalPay Криптовалюта Международная Криптовалюты + СБП
⭐ Telegram Stars Внутренняя валюта Международная Встроенная валюта Telegram
🏦 Monobank Банковские карты Украина Банка (jar) UAH
💰 Heleket Криптовалюта Международная Криптовалютные платежи
💵 Кешбек Внутренний баланс Встроенная Система лояльности
🔧 Sandbox Тестовый режим Локально Только для тестирования
💡 О промокодах: Промокоды работают со всеми платежными системами без исключения. Они применяются до выбора способа оплаты и уменьшают финальную стоимость товара. Подробнее в разделе Промокоды.

🪙 CryptoBot

Криптовалюта

CryptoBot — популярный сервис для приема криптовалютных платежей в Telegram. Поддерживает множество криптовалют (BTC, ETH, USDT, TON и др.).

Получение API токена

Откройте бот CryptoBot

Перейдите в Telegram бот @CryptoBot

Создайте приложение

Используйте команду /app → Create App

Укажите название приложения (например, "My Donate Bot")

Получите API токен

После создания приложения вы получите API Token. Скопируйте его.

Настройка в .env

# CryptoBot Configuration
CRYPTOBOT_ENABLED=true
CRYPTOBOT_TOKEN=your_cryptobot_token_here
CRYPTOBOT_ENABLED
Включить/выключить CryptoBot (true/false)
CRYPTOBOT_TOKEN
API токен из CryptoBot
✅ Готово! CryptoBot настроен. Пользователи смогут оплачивать покупки криптовалютой.

💎 CrystalPay

Криптовалюта Карты РФ (СБП)

CrystalPay — российский сервис для приема криптовалютных платежей. Поддерживает USDT, BTC, ETH, LTC и другие криптовалюты, а также СБП.

Получение учетных данных

Регистрация

Зарегистрируйтесь на crystalpay.io

Создайте кассу

В личном кабинете создайте новую кассу:

  • Перейдите в раздел "Кассы"
  • Нажмите "Создать кассу"
  • Выберите тип кассы (рекомендуется "Анонимная")

Получите учетные данные

В настройках кассы найдите:

  • Логин кассы (auth_login)
  • Секретный ключ #1 (secret)
  • Секретный ключ #2 (salt)

Настройка в .env

# CrystalPay Configuration
CRYSTALPAY_ENABLED=true
CRYSTALPAY_SECRET=your_crystalpay_secret_here
CRYSTALPAY_SALT=your_crystalpay_salt_here
CRYSTALPAY_AUTH_LOGIN=your_crystalpay_auth_login_here
CRYSTALPAY_ENABLED
Включить/выключить CrystalPay (true/false)
CRYSTALPAY_SECRET
Секретный ключ #1 из настроек кассы
CRYSTALPAY_SALT
Секретный ключ #2 из настроек кассы
CRYSTALPAY_AUTH_LOGIN
Логин кассы (не ваш логин на сайте!)
⚠️ Внимание: Минимальная сумма платежа в CrystalPay — 10 рублей. Цены в USD конвертируются по курсу ~90 RUB/USD.

⭐ Telegram Stars

Внутренняя валюта

Telegram Stars — встроенная валюта Telegram для оплаты услуг внутри приложения. Не требует внешних интеграций, работает через Telegram Bot API.

Преимущества

  • ✅ Не требует регистрации в сторонних сервисах
  • ✅ Моментальное зачисление платежей
  • ✅ Низкая комиссия Telegram
  • ✅ Встроенная система возвратов

Настройка в .env

# Telegram Stars Configuration
TELEGRAM_STARS_ENABLED=true
TELEGRAM_STARS_USD_PER_STAR=0.02
TELEGRAM_STARS_MIN_STARS=1
TELEGRAM_STARS_MAX_STARS=2500
TELEGRAM_STARS_ENABLED
Включить/выключить Telegram Stars (true/false)
TELEGRAM_STARS_USD_PER_STAR
Курс конвертации: 1 звезда = X USD (по умолчанию 0.02)
TELEGRAM_STARS_MIN_STARS
Минимальное количество звезд для оплаты
TELEGRAM_STARS_MAX_STARS
Максимальное количество звезд для оплаты (лимит Telegram)
💡 Примечание: Telegram Stars работают автоматически после включения. Убедитесь, что ваш бот имеет права на отправку инвойсов.

🏦 Monobank

Банковские карты

Monobank — украинский банк с возможностью приема платежей через "банку" (jar). Подходит для приема гривны (UAH) от украинских пользователей.

Получение учетных данных

Создайте банку

В приложении Monobank:

  • Откройте раздел "Банки"
  • Создайте новую банку для приема донатов
  • Скопируйте ссылку на банку и её ID

Получите API токен

Для API доступа:

  • Перейдите в настройки → API
  • Создайте персональный токен
  • Скопируйте токен (показывается один раз!)

Настройка в .env

# Monobank Configuration
MONOBANK_ENABLED=true
MONOBANK_TOKEN=your_monobank_token_here
MONOBANK_JAR_ID=your_monobank_jar_id_here
MONOBANK_JAR_URL=https://send.monobank.ua/jar/XXXXX
MONOBANK_MODE=unique_amount
MONOBANK_TIMEOUT_MINUTES=30
MONOBANK_POLL_INTERVAL_SECONDS=60
MONOBANK_MIN_AMOUNT_UAH=10.0
MONOBANK_MARKUP_PERCENT=1.0
MONOBANK_ENABLED
Включить/выключить Monobank (true/false)
MONOBANK_TOKEN
Персональный API токен
MONOBANK_JAR_ID
ID банки для приема платежей
MONOBANK_JAR_URL
Публичная ссылка на банку
MONOBANK_MODE
Режим работы: unique_amount (рекомендуется)
MONOBANK_TIMEOUT_MINUTES
Таймаут ожидания платежа в минутах
MONOBANK_POLL_INTERVAL_SECONDS
Интервал проверки новых платежей (секунды)
MONOBANK_MIN_AMOUNT_UAH
Минимальная сумма платежа в гривнах
MONOBANK_MARKUP_PERCENT
Наценка к курсу валюты в процентах
⚠️ Важно:
  • Monobank API имеет лимит на количество запросов
  • Используется режим "уникальной суммы" для идентификации платежей
  • Курс USD/UAH обновляется автоматически через API Monobank

💰 Heleket

Криптовалюта

Heleket — сервис для приема криптовалютных платежей с поддержкой множества монет.

Получение учетных данных

Регистрация

Зарегистрируйтесь на heleket.com

Создайте магазин

В личном кабинете создайте новый магазин/проект

Получите API ключ

В настройках магазина найдите:

  • API Key
  • Merchant ID (опционально)

Настройка в .env

# Heleket Configuration
HELEKET_ENABLED=true
HELEKET_API_KEY=your_heleket_api_key_here
HELEKET_MERCHANT_ID=your_heleket_merchant_id_here
HELEKET_ENABLED
Включить/выключить Heleket (true/false)
HELEKET_API_KEY
API ключ из настроек магазина
HELEKET_MERCHANT_ID
ID магазина (merchant ID)
💡 Примечание: Минимальная сумма платежа через Heleket — 1.00 USD.

💵 Кешбек

Внутренняя система

Кешбек — встроенная система лояльности для поощрения постоянных клиентов. Пользователи получают процент от покупок обратно на внутренний баланс, который можно использовать для оплаты будущих покупок.

Как работает система кешбека

  • ✅ Пользователь получает процент кешбека после оплаты товара
  • ✅ Процент кешбека настраивается индивидуально для каждого товара
  • ✅ Накопленный кешбек можно использовать как способ оплаты
  • ✅ Можно оплатить товар полностью или частично кешбеком
  • ✅ Администраторы могут вручную пополнять или списывать кешбек

Возможности

Начисление кешбека

При каждой покупке пользователь получает кешбек по формуле:

Кешбек = (Сумма покупки - Использованный кешбек) × Процент товара

Например: товар за $10 с 5% кешбеком → пользователь получит $0.50 на баланс

Использование кешбека

Кешбек становится доступен как отдельный способ оплаты в списке платежных систем. Пользователь может выбрать, сколько кешбека использовать для текущей покупки (вплоть до 100% стоимости).

Администрирование

Через админ-панель бота доступны функции:

  • Пополнение кешбека пользователю
  • Списание кешбека
  • Просмотр истории транзакций
  • Просмотр баланса любого пользователя

Настройка в config.yaml

Глобальное включение/выключение кешбека настраивается в файле donate-bot/src/config/config.yaml: 

subscriptions:
  cashback_enabled: true  # Включить систему кешбека

Настройка процента кешбека для товара

Процент кешбека устанавливается индивидуально для каждого товара в donate-bot/src/config/items.yaml: 

items:
  - id: vip_rank
    name: "VIP Статус"
    price_usd: 10.00
    cashback_percentage: 5.0  # 5% кешбека
    # ... другие параметры
cashback_percentage
Процент кешбека для товара (0-100). По умолчанию 0 (без кешбека)

Ограничения и особенности

⚠️ Важные моменты:
  • Кешбек начисляется только с реально оплаченной суммы (если товар куплен частично за кешбек, начисление идет только с оставшейся части)
  • Максимальное покрытие покупки кешбеком — 100% (можно настроить через max_cashback_coverage)
  • Кешбек доступен как способ оплаты только при наличии достаточного баланса
  • История всех транзакций сохраняется в базе данных

Примеры использования

Пример 1: Полная оплата кешбеком

Баланс пользователя: $15.00
Товар: VIP за $10.00
Действие: Оплата полностью кешбеком
Результат: -$10.00 с баланса, остаток $5.00

Пример 2: Частичная оплата кешбеком

Баланс пользователя: $3.00
Товар: Premium за $10.00 (5% кешбек)
Действие: Использовать $3.00 кешбека + $7.00 другим способом
Результат: 
  - Списано $3.00 кешбека
  - Оплачено $7.00 через CryptoBot
  - Начислено $0.35 кешбека (5% от $7.00)

Пример 3: Начисление кешбека

Товар: Donate $50 (10% кешбек)
Оплата: $50.00 через Telegram Stars
Результат: Начислено $5.00 кешбека

Команды для пользователей

  • /cashback — просмотр баланса и истории транзакций
  • При покупке товара кешбек автоматически отображается как способ оплаты

Команды для администраторов

  • /admin → Кешбек → Пополнить кешбек
  • /admin → Кешбек → Отозвать кешбек
  • В карточке пользователя (/whois) отображается текущий баланс
✅ Преимущества:
  • Повышает лояльность постоянных клиентов
  • Стимулирует повторные покупки
  • Не требует внешних интеграций
  • Полный контроль администратора
  • Прозрачная история операций

🔧 Sandbox (Тестовый режим)

Тестирование

Sandbox — встроенный тестовый режим для отладки платежной системы без реальных транзакций.

Возможности

  • ✅ Имитация успешных платежей
  • ✅ Симуляция ошибок и отказов
  • ✅ Автоматическое подтверждение через N секунд
  • ✅ Не требует внешних сервисов

Настройка в .env

# Sandbox Configuration
SANDBOX_ENABLED=true
SANDBOX_AUTO_CONFIRM_SECONDS=30
SANDBOX_SIMULATE_FAILURES=false
SANDBOX_SHOW_SIMULATE_BUTTON=false
SANDBOX_ENABLED
Включить/выключить Sandbox (true/false)
SANDBOX_AUTO_CONFIRM_SECONDS
Автоматическое подтверждение через N секунд
SANDBOX_SIMULATE_FAILURES
Случайная симуляция ошибок (true/false)
SANDBOX_SHOW_SIMULATE_BUTTON
Показывать кнопку симуляции админам (true/false)
🚨 Важно: Sandbox режим доступен только для администраторов бота. Не используйте его в продакшене!

🎫 Промокоды

Внутренняя система

Промокоды — встроенная система для бесплатной выдачи товаров по кодам. Можно использовать для акций, розыгрышей или компенсаций.

Настройка в .env

# Promocodes Configuration
PROMOCODES_ENABLED=true
PROMOCODES_ENABLED
Включить/выключить систему промокодов (true/false)
💡 Управление промокодами: Создание и управление промокодами доступно через админ-панель бота.

⚙️ Общие настройки

Приоритет платежных систем

Порядок отображения платежных систем настраивается в файле donate-bot/src/config/payments.yaml: 

payments:
  - id: cryptobot
    priority: 10  # Выше = раньше показывается
    enabled: true
  - id: crystalpay
    priority: 9
    enabled: true
  # ...

Отключение платежных систем

Чтобы полностью отключить платежную систему, установите в .env: 

# Отключить CryptoBot
CRYPTOBOT_ENABLED=false

Выборочное включение для товаров

В payments.yaml можно настроить, какие платежные системы доступны для конкретных товаров: 

payments:
  - id: telegram_stars
    supported_products: ["vip", "premium"]  # Только для этих товаров
    excluded_products: ["donate"]          # Исключить для этих товаров

🔧 Решение проблем

Платежная система не отображается

  • ✅ Проверьте, что XXXXX_ENABLED=true в .env
  • ✅ Убедитесь, что все обязательные параметры заполнены
  • ✅ Проверьте логи бота на наличие ошибок инициализации
  • ✅ Перезапустите бота после изменения .env

Платежи не приходят

  • ✅ Для Monobank: проверьте корректность токена и ID банки
  • ✅ Для криптоплатежей: убедитесь, что webhook настроен (если требуется)
  • ✅ Проверьте логи на ошибки API запросов
  • ✅ Убедитесь, что минимальная сумма платежа соблюдена

Ошибки API

  • ✅ CryptoBot: проверьте срок действия токена
  • ✅ CrystalPay: убедитесь, что используется логин кассы, а не сайта
  • ✅ Monobank: не превышайте лимит запросов API (60 в минуту)
  • ✅ Проверьте, что API endpoint доступен (не заблокирован файрволом)

Логирование

Все платежные операции логируются с префиксом [PAYMENT_SYSTEM]. Для отладки включите DEBUG уровень логирования: 

# В bot.py или config
import logging
logging.basicConfig(level=logging.DEBUG)

❓ Часто задаваемые вопросы

Можно ли использовать несколько платежных систем одновременно?

Да! Бот поддерживает неограниченное количество активных платежных систем. Пользователь выбирает удобный способ оплаты из доступных.

Как изменить курс конвертации для Telegram Stars?

Измените параметр TELEGRAM_STARS_USD_PER_STAR в .env. По умолчанию 1 звезда = $0.02 USD.

Нужен ли VPS для работы платежных систем?

Для большинства систем — нет. Telegram Stars, CryptoBot, CrystalPay работают через polling. Monobank использует периодическую проверку. Webhook требуется только для оптимальной работы.

Какая комиссия у платежных систем?

  • Telegram Stars: комиссия Telegram (~30% от суммы)
  • CryptoBot: нет комиссии для получателя
  • CrystalPay: 2-4% в зависимости от валюты
  • Monobank: без комиссии для держателя банки
  • Heleket: уточняйте на сайте сервиса

Как настроить процент кешбека для разных товаров?

Процент кешбека настраивается индивидуально в конфиге каждого товара через параметр cashback_percentage. Вы можете установить разные проценты: VIP — 5%, Premium — 10%, донаты — 15% и т.д. Система автоматически рассчитает и начислит кешбек.

Можно ли ограничить использование кешбека?

Да, через параметр max_cashback_coverage можно установить максимальное покрытие покупки кешбеком (например, 0.5 = максимум 50% оплаты кешбеком). По умолчанию установлено 1.0 (100% покрытие).

🎉 Готово! Теперь ваш бот готов принимать платежи через выбранные системы. При возникновении проблем обратитесь к логам бота или документации конкретного провайдера.