Платёжные системы

Подключение агрегаторов и бонусы за пополнение

Оплату подключают в .env, а не в админке. Ключи агрегаторов не должны попадать ни в базу, ни на экран. У каждого провайдера свой флаг и свой набор ключей.

Что поддерживается

Провайдер	Переменные
Unitpay	`UNITPAY_ENABLED`, `UNITPAY_PUBLIC_KEY`, `UNITPAY_SECRET_KEY`
FreeKassa	`FREEKASSA_ENABLED`, `FREEKASSA_MERCHANT_ID`, `FREEKASSA_SECRET_KEY`, `FREEKASSA_SECRET_KEY_SECOND`
Enot.io	`ENOTIO_ENABLED`, `ENOTIO_MERCHANT_ID`, `ENOTIO_SECRET_KEY`, `ENOTIO_SECRET_KEY_SECOND`
PayOk	`PAYOK_ENABLED`, `PAYOK_SHOP_ID`, `PAYOK_SECRET_KEY`
AnyPay	`ANYPAY_ENABLED`, `ANYPAY_MERCHANT_ID`, `ANYPAY_SECRET_KEY`
CentApp	`CENTAPP_ENABLED`, `CENTAPP_SHOP_ID`, `CENTAPP_TOKEN`

Провайдеров можно включить сколько угодно, игрок выберет способ в кабинете. Если не включён ни один, кнопка пополнения не появится.

Если забыть ключ

Если поставить *_ENABLED=1 и не заполнить ключи, приложение не стартует и напишет, чего именно не хватает. Лучше упасть на старте, чем узнать от игрока, что оплата не работает.

Как настроить

Завести магазин у агрегатора

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

Указать адреса возврата и уведомлений

Три адреса, которые агрегатор спросит:

Что	Адрес
Успех	`https://api.example.com/payment/redirect/success/<провайдер>`
Неуспех	`https://api.example.com/payment/redirect/fail/<провайдер>`
Уведомление	`https://api.example.com/payment/methods/<провайдер>/handler`

Вместо <провайдер> подставьте unitpay, freekassa, enotio, payok, anypay или centapp.

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

Прописать ключи в `.env` и перезапустить

UNITPAY_ENABLED=1
UNITPAY_PUBLIC_KEY=...
UNITPAY_SECRET_KEY=...

Проверить реальным платежом

На минимальную сумму, с настоящей карты. Тестовые режимы агрегаторов часто ведут себя не так, как боевые, особенно с подписью уведомления.

Как сервер проверяет уведомление

Отсюда растут 90% проблем «оплатил, деньги не пришли», поэтому механику лучше знать.

Приходит POST на handler от агрегатора.
Сервер сверяет IP отправителя со списком адресов провайдера.
Сервер пересчитывает подпись по своему секретному ключу и сравнивает с присланной.
Если всё сошлось, счёт помечается оплаченным и баланс пополняется.

TRUST_PROXY

Если сайт за nginx, а TRUST_PROXY в .env пустой, сервер видит IP прокси вместо IP агрегатора и отклоняет все уведомления. Симптом ровно тот: у агрегатора платежи проходят, а баланс не растёт. Разбор на странице про .env.

Второй по частоте случай — не тот секретный ключ. У FreeKassa и Enot.io их два: одним подписывают ссылку на оплату, другим проверяют уведомление. Если поменять их местами, симптомы будут те же.

Бонусы за пополнение

E-Commerce → Пополнение. Таблица порогов: пополнил на столько-то, получил процент сверху.

Сумма	Бонус к пополнению, %
500	5
1000	10
3000	15

Работает ступеньками: сервер берёт самый высокий порог, который платёж перешагнул, и считает процент от всей суммы платежа. При такой таблице пополнение на 1200 зачислит 1320.

Бонус приходит в ту же реальную валюту, а не в бонусную. Каждому порогу можно задать иконку, тогда на странице пополнения они показываются списком наград.

Если порогов нет, игрок получает ровно сумму платежа.

Жизненный цикл платежа

Счёт создаётся, когда игрок нажимает «Пополнить», и остаётся в базе, даже если вкладку закрыли. Брошенные счета копятся быстро, поэтому в настройках есть автоочистка: ставьте 7–14 дней.

Оплаченные платежи лучше хранить дольше: именно к ним приходят с «я платил, где деньги». В карточке платежа видно сумму, метод, ID счёта у агрегатора и IP, с которого пришло уведомление.

Платёжные системы

Содержание