feat(payments): settle the direct rail through YooKassa

Replace Robokassa with YooKassa as the RUB direct-rail provider. The wallet
model is untouched: one `direct` segment, the same spend wall, the same
per-channel merchant shops (D42) and `shop` on the order (D44).

The two providers are not shaped alike, and that drives the change:

- Opening a purchase is now an outbound API call (`POST /v3/payments`,
  single-stage capture, redirect confirmation). The order id is both the
  `Idempotence-Key` and `metadata.order_id`, so a retried create cannot mint a
  second payment and a notification always resolves to its order.
- YooKassa does NOT sign notifications, so the body is never evidence: it only
  names a payment, which is re-read with `GET /v3/payments/{id}`, and only that
  answer is acted on. Two guards ride on it — the payment's metadata must name
  the order, and its `test` flag must match the shop's, so a test-shop payment
  can never credit real chips. The sender address is checked against YooKassa's
  published ranges first, which stops a forger turning each fabricated
  notification into an outbound call of ours.
- A notification lost for good would leave the money taken and the chips unowed,
  silently. The existing pending-order reaper now asks the provider about each
  order that reached its expiry age carrying a payment id, and credits the ones
  really paid — one request per order over its whole life, not polling.
- `payment.canceled` records a `failed` event, so a declined payment is finally
  surfaced to the customer as PAYMENTS.md §9 already specified.
- The admin refund moves the money through `POST /v3/refunds` before recording
  anything; a failed call records nothing, so the ledger cannot claim a refund
  that did not happen, and the recorded id is the provider's own.
- YooKassa has no cabinet-side generic receipt: «Чеки от ЮKassa» registers one
  only if the request carries it, so every payment and refund now sends an
  itemized `receipt` to the D36 confirmed email. The VAT rate code is a deploy
  variable; the settlement subject and method are constants.

Robokassa is retired, not deleted: the direct rail falls back to it when no
YooKassa shop is configured and no deployment sets its credentials, so reviving
it is a credentials change rather than a code change. Its variables are removed
from compose, .env.example, write-prod-env.sh and the three workflows, and
recorded in backend/internal/robokassa/README.md together with the cabinet
configuration and the revival steps. Ledger rows keep `provider = 'robokassa'`;
that literal is load-bearing for the idempotency index.

No migration and no wire change: `orders.provider_payment_id` already existed,
and the client is rail-agnostic.

Decisions D47-D51 (revising D41) and stage E12 are baked into the docs.

deploy/.env.example

@@ -132,28 +132,30 @@ GATEWAY_VK_APP_SECRET=
 # come from VITE_VK_APP_ID / VITE_VK_ID_REDIRECT_URL above. All three empty disables link.vk.*.
 GATEWAY_VK_ID_CLIENT_SECRET=
 
-# --- Payments: Robokassa (direct RUB rail) ----------------------------------
-# The shop's merchant login + the two pass phrases (Password1 signs the launch request,
-# Password2 signs/verifies the Result callback). An empty login leaves the direct rail off.
-# ROBOKASSA_TEST=1 runs test payments against the shop's TEST pass phrases (no real money);
-# empty/0 is live. Mapped in compose to BACKEND_ROBOKASSA_*; Gitea TEST_/PROD_ secrets, with
-# PROD_BACKEND_ROBOKASSA_TEST a variable so go-live is a flag flip, not a secret redeploy.
-ROBOKASSA_MERCHANT_LOGIN=
-ROBOKASSA_PASSWORD1=
-ROBOKASSA_PASSWORD2=
-ROBOKASSA_TEST=
-# Multi-shop direct rail (D42): the vars above seed the "web" channel; add per-channel shops here.
-# ROBOKASSA_WEB_* overrides the web shop; ROBOKASSA_ANDROID_* adds the android (RuStore) shop. Each
-# credits the one direct wallet; an empty login drops that channel (routing falls back to web). The
-# Robokassa cabinet points each shop's Result URL at /pay/robokassa/result/web and .../android.
-ROBOKASSA_WEB_MERCHANT_LOGIN=
-ROBOKASSA_WEB_PASSWORD1=
-ROBOKASSA_WEB_PASSWORD2=
-ROBOKASSA_WEB_TEST=
-ROBOKASSA_ANDROID_MERCHANT_LOGIN=
-ROBOKASSA_ANDROID_PASSWORD1=
-ROBOKASSA_ANDROID_PASSWORD2=
-ROBOKASSA_ANDROID_TEST=
+# --- Payments: YooKassa (direct RUB rail) ------------------------------------
+# One merchant shop per channel (D42): the shop id (Настройки — Магазин, field shopId) and the
+# secret key (Интеграция — Ключи API). Each shop credits the one direct wallet; a shop missing
+# either credential drops that channel (order routing falls back to web), and no shop at all
+# leaves the direct rail off. YOOKASSA_*_TEST=1 marks a TEST shop, which makes the intake refuse
+# to credit a live payment against it (and a test payment against a live shop).
+# Mapped in compose to BACKEND_YOOKASSA_*; Gitea TEST_/PROD_ secrets.
+# Set each shop's notification URL in its cabinet (Интеграция — HTTP-уведомления) to
+# ${PUBLIC_BASE_URL}/pay/yookassa/notify, events payment.succeeded + payment.canceled.
+YOOKASSA_WEB_SHOP_ID=
+YOOKASSA_WEB_SECRET_KEY=
+YOOKASSA_WEB_TEST=
+# The android (RuStore) shop — add when that channel gets its own merchant account.
+YOOKASSA_ANDROID_SHOP_ID=
+YOOKASSA_ANDROID_SECRET_KEY=
+YOOKASSA_ANDROID_TEST=
+# VAT rate code on every fiscal receipt line (54-ФЗ tag 1199): 1 = «Без НДС» (УСН/ПСН), 4 = 20%,
+# 11 = 22%. A Gitea VARIABLE, not a secret, so a rate change is a variable edit + redeploy.
+YOOKASSA_VAT_CODE=1
+#
+# Robokassa (the retired direct rail) is deliberately absent here: no deployment sets its
+# credentials, which is what keeps it dormant. The backend still reads BACKEND_ROBOKASSA_* and
+# falls the direct rail back to it if they are ever set again — see
+# backend/internal/robokassa/README.md for the full variable set and how to revive the rail.
 
 # --- Gateway anti-abuse ------------------------------------------------------
 # Planted honeytoken bearer value: any request presenting it is flagged — a 24h IP ban

deploy/README.md

@@ -76,10 +76,10 @@ compose binds from this directory.
 | `GM_BASICAUTH_HASH` | secret | bcrypt hash gating `/_gm` (admin console + Grafana). Generate with `docker run --rm caddy:2-alpine caddy hash-password --plaintext '<pw>'`. |
 | `TELEGRAM_MINIAPP_URL` | derived | The Mini App URL the bot hands out in deep links / buttons. The deploy derives `PUBLIC_BASE_URL + /telegram/`; set it directly only for a local run (compose still `:?`-requires it). |
 | `EXPORT_SIGN_KEY` | secret | HMAC key signing the public finished-game export download URLs (`/dl/*`). Generate with `openssl rand -base64 32`. |
-| `BACKEND_ROBOKASSA_MERCHANT_LOGIN` | secret | Robokassa shop login for the direct RUB rail. Empty leaves the rail off. |
-| `BACKEND_ROBOKASSA_PASSWORD1` / `…_PASSWORD2` | secret | Robokassa pass phrases: Password1 signs the launch request, Password2 signs/verifies the Result callback. Use the shop's **test** pair while `…_ROBOKASSA_TEST=1`, the **live** pair for real money. (Password3 — Robokassa's JWT-invoice API — is unused.) |
-| `BACKEND_ROBOKASSA_TEST` | **variable** | `1` runs test payments against the test pass phrases (no real money); empty/`0` is live. A variable, not a secret, so go-live is a flag flip + redeploy, not a secret rotation. |
-| `BACKEND_ROBOKASSA_{WEB,ANDROID}_{MERCHANT_LOGIN,PASSWORD1,PASSWORD2,TEST}` | secret / variable | Multi-shop direct rail (D42): per-channel Robokassa shops. The legacy `BACKEND_ROBOKASSA_*` seeds the **web** shop; `…_WEB_*` overrides it, `…_ANDROID_*` adds the **android** (RuStore) shop. Each credits the one `direct` wallet; the cabinet Result URL per shop is `/pay/robokassa/result/{web,android}`. Empty login ⇒ that channel unconfigured (order routing falls back to the web shop). |
+| `BACKEND_YOOKASSA_{WEB,ANDROID}_SHOP_ID` | secret | YooKassa shop id for that channel of the direct RUB rail (cabinet: **Настройки — Магазин**, field `shopId`). Empty ⇒ that channel is unconfigured and order routing falls back to the **web** shop; no channel configured at all leaves the rail off. |
+| `BACKEND_YOOKASSA_{WEB,ANDROID}_SECRET_KEY` | secret | That shop's API secret key (cabinet: **Интеграция — Ключи API**). It is the password half of the HTTP Basic credentials on every API call. A shop id without a secret key is ignored. |
+| `BACKEND_YOOKASSA_{WEB,ANDROID}_TEST` | **variable** | `1` marks the credentials as a **test shop**: the intake then refuses to credit anything but a test payment (and a live shop refuses a test one). A variable, not a secret, so switching a contour between a test and a live shop is a flag flip + redeploy. |
+| `BACKEND_YOOKASSA_VAT_CODE` | **variable** | VAT rate code stamped on every fiscal receipt line (54-ФЗ tag 1199): `1` = «Без НДС» (УСН/ПСН), `4` = 20%, `11` = 22%. Defaults to `1`. A variable so a rate change needs no code change. **Confirm it with the accountant before the first real payment** — a wrong rate produces wrong receipts, not a failed payment, so it fails silently. |
 
 **Plus the bot token** — `TELEGRAM_BOT_TOKEN` (secret), shared by the validator (HMAC
 secret) and the bot (Bot API). It defaults to empty in compose, but both **fail at

deploy/docker-compose.yml

@@ -164,25 +164,21 @@ services:
       # recipient(s) (comma-separated allowed). Both empty disables the alert worker.
       BACKEND_SMTP_ADMIN_FROM: ${SMTP_RELAY_ADMIN_FROM:-}
       BACKEND_ADMIN_EMAIL: ${ADMIN_EMAIL:-}
-      # Direct-rail (Robokassa) payment intake: the merchant login + Password1/Password2 and the
-      # test-mode flag (deploy env: TEST_/PROD_BACKEND_ROBOKASSA_*). An empty login leaves the
-      # direct order and Result-callback endpoints unregistered (the rail is off).
-      BACKEND_ROBOKASSA_MERCHANT_LOGIN: ${ROBOKASSA_MERCHANT_LOGIN:-}
-      BACKEND_ROBOKASSA_PASSWORD1: ${ROBOKASSA_PASSWORD1:-}
-      BACKEND_ROBOKASSA_PASSWORD2: ${ROBOKASSA_PASSWORD2:-}
-      BACKEND_ROBOKASSA_TEST: ${ROBOKASSA_TEST:-}
-      # Per-channel shops for the multi-shop direct rail (D42): the legacy ROBOKASSA_* above seeds
-      # the "web" channel; ROBOKASSA_WEB_* overrides it and ROBOKASSA_ANDROID_* adds the android
-      # shop. Each shop credits the one direct wallet; an empty login drops that channel (order
-      # routing falls back to the web shop). Result URLs: /pay/robokassa/result/{web,android}.
-      BACKEND_ROBOKASSA_WEB_MERCHANT_LOGIN: ${ROBOKASSA_WEB_MERCHANT_LOGIN:-}
-      BACKEND_ROBOKASSA_WEB_PASSWORD1: ${ROBOKASSA_WEB_PASSWORD1:-}
-      BACKEND_ROBOKASSA_WEB_PASSWORD2: ${ROBOKASSA_WEB_PASSWORD2:-}
-      BACKEND_ROBOKASSA_WEB_TEST: ${ROBOKASSA_WEB_TEST:-}
-      BACKEND_ROBOKASSA_ANDROID_MERCHANT_LOGIN: ${ROBOKASSA_ANDROID_MERCHANT_LOGIN:-}
-      BACKEND_ROBOKASSA_ANDROID_PASSWORD1: ${ROBOKASSA_ANDROID_PASSWORD1:-}
-      BACKEND_ROBOKASSA_ANDROID_PASSWORD2: ${ROBOKASSA_ANDROID_PASSWORD2:-}
-      BACKEND_ROBOKASSA_ANDROID_TEST: ${ROBOKASSA_ANDROID_TEST:-}
+      # Direct-rail (YooKassa) payment intake, one merchant shop per channel (D42): the shop id +
+      # secret key and a flag marking a test shop (deploy env: TEST_/PROD_BACKEND_YOOKASSA_*).
+      # Each shop credits the one direct wallet; a shop missing either credential drops that
+      # channel (order routing falls back to the web shop), and no shop at all leaves the direct
+      # order and notification endpoints unregistered. Notification URL (set per shop in the
+      # YooKassa cabinet): ${PUBLIC_BASE_URL}/pay/yookassa/notify.
+      BACKEND_YOOKASSA_WEB_SHOP_ID: ${YOOKASSA_WEB_SHOP_ID:-}
+      BACKEND_YOOKASSA_WEB_SECRET_KEY: ${YOOKASSA_WEB_SECRET_KEY:-}
+      BACKEND_YOOKASSA_WEB_TEST: ${YOOKASSA_WEB_TEST:-}
+      BACKEND_YOOKASSA_ANDROID_SHOP_ID: ${YOOKASSA_ANDROID_SHOP_ID:-}
+      BACKEND_YOOKASSA_ANDROID_SECRET_KEY: ${YOOKASSA_ANDROID_SECRET_KEY:-}
+      BACKEND_YOOKASSA_ANDROID_TEST: ${YOOKASSA_ANDROID_TEST:-}
+      # VAT rate code stamped on every fiscal receipt line (54-ФЗ tag 1199). 1 = «Без НДС» (УСН/ПСН).
+      # A deploy variable, not a secret, so a rate change is a variable edit + redeploy.
+      BACKEND_YOOKASSA_VAT_CODE: ${YOOKASSA_VAT_CODE:-1}
     # The dictionary lives on a named volume seeded from the image on first boot
     # (the image's /opt/dawg is owned by the nonroot UID, which the fresh volume
     # inherits). The admin console writes new version subdirectories here, and the

deploy/write-prod-env.sh

@@ -54,10 +54,13 @@ export GATEWAY_RECOMMENDED_CLIENT_VERSION='$GATEWAY_RECOMMENDED_CLIENT_VERSION'
 export TELEGRAM_BOT_TOKEN='$TELEGRAM_BOT_TOKEN'
 export TELEGRAM_MINIAPP_URL='$TELEGRAM_MINIAPP_URL'
 export GATEWAY_VK_APP_SECRET='$GATEWAY_VK_APP_SECRET'
-export ROBOKASSA_MERCHANT_LOGIN='$ROBOKASSA_MERCHANT_LOGIN'
-export ROBOKASSA_PASSWORD1='$ROBOKASSA_PASSWORD1'
-export ROBOKASSA_PASSWORD2='$ROBOKASSA_PASSWORD2'
-export ROBOKASSA_TEST='$ROBOKASSA_TEST'
+export YOOKASSA_WEB_SHOP_ID='$YOOKASSA_WEB_SHOP_ID'
+export YOOKASSA_WEB_SECRET_KEY='$YOOKASSA_WEB_SECRET_KEY'
+export YOOKASSA_WEB_TEST='$YOOKASSA_WEB_TEST'
+export YOOKASSA_ANDROID_SHOP_ID='$YOOKASSA_ANDROID_SHOP_ID'
+export YOOKASSA_ANDROID_SECRET_KEY='$YOOKASSA_ANDROID_SECRET_KEY'
+export YOOKASSA_ANDROID_TEST='$YOOKASSA_ANDROID_TEST'
+export YOOKASSA_VAT_CODE='${YOOKASSA_VAT_CODE:-1}'
 export VITE_VK_APP_ID='$VITE_VK_APP_ID'
 export VITE_VK_ID_REDIRECT_URL='$VITE_VK_ID_REDIRECT_URL'
 export GATEWAY_VK_ID_CLIENT_SECRET='$GATEWAY_VK_ID_CLIENT_SECRET'