Подключение платёжных систем

1. 01 -

   Игрок выбрал товар на витрине, нажал "Оплатить" → shop отправляет POST /payments в backend с productId, ником, email и id метода оплаты.

2. 02 -

   Backend создаёт запись payment, идёт в API провайдера (например YooKassa) и получает confirmation_url - ссылку, куда отправить игрока.

3. 03 -

   Игрок попадает на страницу провайдера, вводит карту/крипту/СБП и оплачивает. По результату его редиректит на PAYMENT_RETURN_URL магазина.

4. 04 -

   Параллельно провайдер шлёт серверный вебхук на WEBHOOK_BASE_URL/webhooks/<provider>. Backend проверяет подпись/IP, помечает платёж paid и кладёт его в очередь доставки.

5. 05 -

   Плагин или RCON забирает покупку из очереди и выдаёт её игроку. Покупателю на почту уходит email-чек.

※ Комиссии указаны ориентировочно - реальный процент зависит от твоего договора с провайдером.

В админ-панели открой Магазин → Платёжные системы. Слева - форма провайдера, справа - список всех доступных шлюзов. Выбери нужный и переключи "Включить" наверху страницы.

После сохранения настройки лежат в БД (payment_providers), backend не нужно перезапускать - изменения подхватятся на следующем запросе.

※ Бекенд при старте делает seed - создаёт все 6 шлюзов с пустыми credentials в выключенном состоянии. Если в базе уже есть запись с твоими ключами, повторный seed её не затрёт.

В личном кабинете yookassa.ru зайди в Интеграция → Ключи API. Тебе нужны:

Затем настрой webhook: Интеграция → HTTP-уведомления → Добавить. Адрес:

Подпиши уведомления на события: payment.succeeded, payment.canceled, refund.succeeded.

※ ЮKassa не подписывает вебхуки - аутентификация по списку IP. Backend проверяет, что вебхук пришёл с 185.71.76/77.*, 77.75.153/156/157.* или 2a02:5180:*. Если ты за прокси без x-forwarded-for - поставь в .env YOOKASSA_SKIP_IP_CHECK=true, но только в тестовом режиме.

В личном кабинете heleket.com создай мерчанта и забери:

При создании мерчанта (или в его настройках) укажи URL вебхука:

Валюта аккаунта - в карточке провайдера выбери одну из: USD, EUR, RUB. Если товары в другой валюте, сумма пересчитается по курсам из общих настроек магазина.

※ Heleket дополнительно проверяет IP-источник (31.133.220.*) И MD5-подпись каждого webhook. Подпись считается как md5(base64(json_body) + apiKey).

Открой в Telegram бота @CryptoBot (или @CryptoTestnetBot для песочницы) → Crypto Pay (/pay) → Create App. Получишь:

В том же приложении CryptoBot включи Webhooks и укажи URL:

Включи тестовый режим в админке, если используешь токен от @CryptoTestnetBot - тогда backend будет ходить в testnet-pay.crypt.bot вместо боевого pay.crypt.bot.

※ CryptoBot подписывает вебхук HMAC-SHA256 от сырого тела, ключ - sha256(apiToken), заголовок - crypto-pay-api-signature. Подпись считается по байтам, которые приходят в запросе.

Для подключения подайте заявку на сайте wata.pro, при подаче укажите тип верификации "Рекомендация" и введите FreshDonate

В кабинете wata.pro (или api-sandbox.wata.pro для теста) выпусти Access Token. Это JWT - подпиши его в кабинете и сразу скопируй (после закрытия модалки токен будет недоступен).

В терминале Wata укажи URL для уведомлений (Предварительно включите "Вебхук оплаты"):

※ Wata подписывает вебхуки RSA-SHA512 по сырому телу, подпись приходит в заголовке X-Signature в base64. Публичный ключ backend сам подтягивает с /api/h2h/public-key и кеширует на время жизни процесса.

В кабинете robokassa.ru зайди в Технические настройки → Технические настройки магазина и забери:

В тех. настройках укажи ResultURL и метод POST:

В админ-панели выбери алгоритм подписи (SHA256 по умолчанию, либо MD5) - он должен совпадать с настройкой в кабинете Robokassa, иначе все вебхуки будут отбиваться 403.

※ Robokassa требует, чтобы InvId был положительным 32-битным числом, а у нас платежи - UUID. Backend хеширует UUID в 31-битный int и передаёт оригинал UUID в Shp_paymentId - именно по нему ResultURL находит платёж и завершает его. На ResultURL обязательно нужно ответить телом OK<InvId>, иначе Robokassa будет долбить вебхук снова и снова.

В Tebex Dashboard создай Webstore типа Minecraft. Далее Webstore Builder → API Keys, забери:

URL вебхука для Tebex:

После добавления endpoint Tebex пришлёт validation.webhook с уникальным id - backend сам ответит этим же id, и endpoint в Tebex перейдёт в "Validated".

※ Базовый URL берётся из WEBHOOK_BASE_URL в .env бекенда. На проде это https://api.your-domain.com, локально - твой ngrok/cloudflared-туннель.

※ Каждый /webhooks/* endpoint защищён rate-limit (200 req/min). Если провайдер ретраит вебхуки часто - повысь RATE_LIMIT_MAX в .env.

В карточке провайдера есть две связанные настройки: commissionPercent (сколько процентов берёт провайдер) и commissionRule (на кого вешать эту комиссию).

Пример: товар 100 ₽, комиссия 2.8%.

※ Комиссия из настроек используется только для предварительного расчёта при создании платежа. Когда платёж проходит, backend перезаписывает её из реального ответа провайдера (income_amount у YooKassa, commission у Heleket и т.п.). Так что в статистике панели цифры будут точными, даже если ты в админке указал чуть-чуть не ту ставку.

У каждого провайдера в админке два важных поля:

Провайдер - это бекенд-сущность. Чтобы игрок увидел его в магазине, нужно создать платёжный метод - кнопку с названием, иконкой и привязкой к провайдеру.

В админ-панели открой Магазин → Методы оплаты → Добавить и заполни:

※ Можно создать несколько методов на одного провайдера - например "Карты РФ" и "СБП" оба на YooKassa, с разными иконками. Покупатель видит только включённые методы.

У некоторых провайдеров в карточке есть тумблер testMode. Что он делает:

Демо-платежи (созданные через кнопку "Тест" в админке, без реального захода в API) не шлют email-чеки покупателю и не попадают в очередь доставки - чтобы не спамить плагин при отладке.

※ В NODE_ENV=development backend пропускает проверку IP/подписи для всех вебхуков. На проде такого делать нельзя - иначе любой сможет послать фейковый "оплачено" и забрать товар.