Онлайн-оплата через ЮKassa

Игрок пополняет кошелёк картой, через СБП или SberPay на странице оплаты ЮKassa; с кошелька оплачиваются брони, прокат и доли за корт.

При подключённом магазине Онлайн-оплата включается, когда клуб подключил магазин ЮKassa и ключи магазина внесены в облако. До этого пополнение отвечает 503 payments_provider_not_configured. Способы оплаты на странице ЮKassa определяются настройками магазина в кабинете ЮKassa.

Поток пополнения

Приложение или сайт от имени игрока создаёт платёж: POST /v1/wallet/topup. Облако заводит у себя запись платежа (pending), создаёт платёж в ЮKassa и возвращает paymentId и confirmationUrl.
Игрок переходит по confirmationUrl и платит на странице ЮKassa.
ЮKassa присылает уведомление на POST /v1/wallet/yookassa/webhook. Облако перепрашивает статус платежа у ЮKassa и, если он оплачен и сумма совпадает, зачисляет деньги на кошелёк.
Игрок возвращается со страницы оплаты; приложение спрашивает GET /v1/wallet/payments/{payment_id}. Если уведомление ещё не дошло, облако само перепрашивает статус у ЮKassa — оплата не теряется.

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

curl -X POST "https://адрес-вашего-сервера/api/v1/wallet/topup" \
  -H "Authorization: Bearer <токен игрока>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000}'
# → {"ok": true, "status": "pending",
#    "paymentId": "e4a19c7d-6b3f-4c21-8d5e-0f2a7b9c1d36",
#    "confirmationUrl": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=…"}

Сумма — целые рубли. Пределы задаются в облаке, по умолчанию от 100 до 100 000 ₽; вне пределов — 400 с {"error": "bad_amount", "min": …, "max": …}.
Платёж создаётся в ЮKassa с немедленным списанием и возвратом игрока по адресу, заданному в облаке. Ключ идемпотентности для ЮKassa — paymentId облака.
ЮKassa недоступна или не создала платёж — 502 payment_create_failed; ничего не списано, запрос можно повторить.
Чек 54-ФЗ: если в облаке включена передача чека, он формируется с телефоном игрока.

Уведомление ЮKassa

В кабинете ЮKassa адрес уведомлений — https://адрес-вашего-сервера/api/v1/wallet/yookassa/webhook, событие — успешный платёж (и, по желанию, отмена).

Тело уведомления на веру не принимается. Уведомления ЮKassa не подписаны, поэтому облако берёт из тела только object.id, а статус и сумму перепрашивает у ЮKassa по ключу магазина и сверяет с собственной записью. Поддельное уведомление ничего не зачислит.

Деньги зачисляются ровно один раз: запись платежа блокируется на время проверки, переход «ожидает → оплачен» делается однажды, повторные уведомления ничего не меняют.
Сумма в ЮKassa не совпала с записью облака — деньги не зачисляются.
Уведомление о чужом платеже — ответ 200 с {"ok": true, "ignored": true}, чтобы ЮKassa не повторяла его. Нет object.id — 400 no_payment_id.

Статус платежа

curl "https://адрес-вашего-сервера/api/v1/wallet/payments/e4a19c7d-6b3f-4c21-8d5e-0f2a7b9c1d36" \
  -H "Authorization: Bearer <токен игрока>"
# → {"paymentId": "e4a19c7d-…", "status": "succeeded", "amount": 5000, "balance": 9200}

Статус	Что значит
`pending`	Ждёт оплаты или ответа ЮKassa. Спросите ещё раз через несколько секунд.
`succeeded`	Оплачен, деньги на кошельке; `balance` — новый баланс.
`canceled`	Отменён в ЮKassa, деньги не зачислены.

Платёж виден только игроку, который его создал; чужой — 404 payment_not_found.

Куда идут деньги кошелька

Баланс и последние 30 операций — GET /v1/wallet. С кошелька оплачиваются брони (POST /v1/bookings), прокат (POST /v1/bookings/{booking_id}/rental) и доли за корт (POST /v1/bookings/splits/{split_id}/accept); возвраты при отмене брони приходят туда же. Платежи, принятые в клубе и проведённые в 1С, тоже зачисляются на кошелёк — см. «Интеграция с 1С».