scrabble-game/docs/PAYMENTS.md

# PAYMENTS — monetization mechanics

Authoritative specification of the monetization domain: the in-game currency, wallets,
benefits, store-compliance rules, payment intake, ads, catalog, ledger, and reporting.
English is authoritative; [`PAYMENTS_ru.md`](PAYMENTS_ru.md) mirrors it in plain Russian
(mirror every point edit in the same PR, like `FUNCTIONAL.md`/`FUNCTIONAL_ru.md`).

Read this before changing any payments behaviour. The technical implementation plan lives
in [`../PLAN.md`](../PLAN.md).

> Status: specification approved; implementation staged (see `PLAN.md`). Nothing here is
> live yet.

## 1. Overview

The game earns through two orthogonal channels:

- **Purchases** of the in-game currency **Фишка** (chips) with real money, then spending
  chips on **values** (benefits).
- **Ads** — a rewarded video tops chips up; an interstitial and a house banner monetize by
  impression.

The currency is **two-tier**:

```
money (VK Votes / TG Stars / RUB via YooKassa)   ─┐
                                                  ├─►  Фишки (chips)  ──►  values
rewarded ad view                                 ─┘                         (no-ads, hints,
                                                                             tournament fee)
```

Chips are the single storefront unit. Money and rewarded views **fund** chips; chips
**buy** values. There is no path that spends money directly on a value — always through
chips.

## 2. Currency model

**One chip is one chip everywhere** — the unit is uniform. The difference between payment
methods lives entirely in the **purchase rate**: a chip pack costs *X* Votes / *Y* Stars /
*Z* RUB, and the rate absorbs each store's commission. Value prices are fixed **in chips**
and identical across methods.

The chip balance is **segmented by `source`** — the platform where the chips were funded:

| `source`   | Funded by                        |
|------------|----------------------------------|
| `vk`       | VK Votes purchase, VK rewarded ad |
| `telegram` | TG Stars purchase                |
| `direct`   | YooKassa purchase (web / native) |

A single account holds all three segments simultaneously: `balance = (account_id, source)`,
up to three rows — a row is materialised lazily on the segment's first funding, and an absent
segment reads as zero. Segmentation is **not** per-identity — see §6.

Why segmented, not one pooled balance: store rules forbid activating value that was paid
for outside the store's own cash desk. Chips funded inside VK (Votes) may only be spent in
the VK context; Stars only inside Telegram; YooKassa-funded (`direct`) chips only outside
the stores. See §4.

**Multi-shop direct rail (D42).** The `direct` rail routes to one YooKassa **merchant shop per
channel** — `web` and `android` (RuStore), `ios` later — chosen by the trusted `X-Platform` subtype;
every shop credits the one `direct` wallet (no per-channel wallet). This is merchant-account
separation for accounting / receipts only: the order records its `shop` (shown in the admin report).
All shops share one notification endpoint, `/pay/yookassa/notify`; an incoming notification is
attributed to a shop by the shop id the payment reports (`recipient.account_id`), falling back to the
channel recorded on the order, and that shop's credentials perform the confirming read (§9).
Standalone apps (Android/iOS) sign in by email only, so a direct purchase always has the D36 email
anchor (D43), which is also where the fiscal receipt is delivered. Fiscalization (54-ФЗ under one ИП)
is a single source regardless of the number of shops (D41).

**Robokassa is retired, not deleted (D47).** It settled the `direct` rail before YooKassa. Its code,
tests and wiring stay in the tree and the rail falls back to it when no YooKassa shop is configured,
so reviving it is a credentials change rather than a code change; no deployment sets those
credentials today. `backend/internal/robokassa/README.md` records the retired variables, the cabinet
configuration and the revival steps. Ledger rows written while it was live keep
`provider = 'robokassa'` — that literal is load-bearing for the idempotency index and is never
renamed or reused.

**Payment availability kill switch (D45/D46).** An operator can disable purchases on a rail/channel
(`direct:web` / `direct:android` / `vk` / `telegram`) or for one account, live from `/_gm`, and the
user sees a localized reason on their next attempt (`payment_unavailable`, carried on the additive
`ExecuteResponse.message`). **Fail-open:** a rail with no status row is enabled. A per-account
`allow` override bypasses only this operational switch, never the security gates (D46).

## 3. Three operations, kept distinct

Do not conflate these — they use different keys:

1. **Fund chips** — money/ad → chip `source` segment, keyed by the **execution context**.
2. **Spend chips = buy a value** — segment → benefit, keyed by context with the gate (§4).
   This is where a benefit is **born** and stamped with its `origin`.
3. **Apply a benefit** over time (e.g. "no-ads until *T*") — governed by the origin rule
   (§5).

`source` (where chips were funded) and `origin` (where a value was bought) share the same
value set `{vk, telegram, direct}` but mean different things. On the web they can diverge:
web spending may draw `vk` chips (`source=vk`) into a `direct` purchase (`origin=direct`).

## 4. Store-compliance gate

The compliance wall is **one-directional**. The dangerous direction — activating externally
paid value *inside* a store wrapper — is blocked; the safe direction (a store benefit
leaking out to the open web) is allowed.

**Spend context → which segments/benefits are usable:**

| Execution context   | Spendable chip segments | Spend priority     |
|---------------------|-------------------------|--------------------|
| Inside VK (Android) | `vk`                    | —                  |
| Inside VK (iOS)     | `vk` (purchase-frozen)  | —                  |
| Inside Telegram     | `telegram`              | —                  |
| Web / native (Direct)| `direct` + `vk` + `telegram` | direct → vk → tg |

- Inside VK/TG only the same-named segment is usable; everything else (chiefly `direct`) is
  invisible-as-spendable there.
- On the web the store has no jurisdiction, so all attached segments are spendable, drained
  by priority direct → vk → tg.
- **VK iOS is a PURCHASE freeze, not a spend freeze.** Apple's ToS forbids only **buying** in-app
  values there (for any currency) — so a purchase (money → chips) is refused. **Spending** VK-wallet
  chips (earned via rewarded ads or bought on the same VK account elsewhere, e.g. VK Android) and
  earning them are legal and stay allowed on VK iOS; a bought benefit also *applies* there. Only the
  money-in step is blocked.

The account is **single** (identities merge, one profile/friends/stats). The gate is
**logical**: in a VK/TG context the server activates only the same-named segment. It rests
on a **trusted platform signal** (§8) — the client is never believed. When the platform
cannot be trusted, the gate is **fail-closed**: spends/purchases are denied, view only.

### One-directional benefit application

A benefit carries `origin` = the **purchase context** (not "what it was paid with"). Buying
on the web with `vk` chips still yields `origin=direct`.

| `origin`         | Where the benefit applies                          |
|------------------|----------------------------------------------------|
| `vk` / `telegram`| **Everywhere** — inside its store *and* out on web/native |
| `direct`         | **Only** web/native — never inside VK/TG (= store ban) |

Before a web spend draws `vk`/`telegram` chips, the UI **warns** the user that the value
will be available here (web/native) only, because of VK/TG restrictions.

## 5. Benefits

Three distinct entities, do not merge:

- **Chips** — currency. Segment by `source`.
- **Hints** — consumable, bought with chips. Segment by `origin`. Spent one-per-hint in
  online games; `vs_ai` hints stay free/unlimited (30-min idle gate, not counted). A hint
  spent in a game is drawn from an `origin` applicable to the current context (same
  one-directional relaxation as above).
- **No-ads** — a duration benefit, bought with chips. Segment by `origin`.

**No-ads stacking.** Buying a term extends `paid_until[origin] += term` from
`max(now, current end)` — the remainder is never lost ("terms add up"). **Forever** is a
separate perpetual flag that overrides terms. "Ads off in context *P*" ⇔ some `origin`
applicable in *P* has `paid_until > now` (on the web take the max over direct/vk/tg; in VK
only vk; in TG only tg).

**What no-ads suppresses:** the top banner **and** the post-move fullscreen interstitial.
The voluntary **rewarded** view (for chips) is never suppressed — it is the user's choice.

**Tournament fee** — a future value type; the atom is provisioned but the mechanic ships
later.

## 6. Wallet lifecycle

**Segment availability rule.** A segment is spendable ⇔ the account has an identity of that
`source` (for `direct`: a durable identity/email). This makes unlink/merge fall out
naturally.

**Unlink (vk/tg).** Allowed even with a non-zero balance/active benefit. The segment is not
burned — it **sleeps** (no identity ⇒ unavailable in VK *and*, lacking the attachment,
unavailable as an attached web segment); re-linking wakes it. The user is warned before
unlinking ("N chips will be unavailable until you re-link"). The last identity cannot be
unlinked (existing `ErrLastIdentity`).

**Merge.** Segments and benefits merge **by origin**: same-origin segments add (chips sum,
benefit terms extend per origin), different origins coexist. This extends the current
account-merge (`hint_balance +=`, `paid_account OR=`) so origin is preserved and nothing
leaks across platforms.

**Guest.** A guest account has **no wallet at all** — the Wallet section is hidden, no
purchases, no balance, by design. Balances belong only to durable accounts. The guest
reaper therefore deletes guests freely (no money can exist there). In `direct`, email is
required **before the first purchase** as a recovery anchor (in VK/TG the vk/tg identity is
already the anchor); the existing email flow (request code → confirm → clear guest →
durable) is reused.

## 7. Catalog and pricing

The catalog is **configurable** — products, prices, purchase rates, and rewarded payout
live in the database and are edited in the admin console, no release required.

- **Base values (atoms):** chips, hints, no-ads days, tournament entry.
- **Product = a set of atoms + a price.** Sold singly or as a combo (e.g. "250 hints + 30
  no-ads days").
- **Chip pack** (funds chips) — priced **per method** (multi-currency Votes/Stars/RUB) as a
  single product.
- **Value** (bought with chips) — priced **in chips** (uniform across methods).

**Deactivation, not deletion.** Products are soft-deleted (deactivated). A completed
purchase stores a **snapshot** of what was sold (atom composition + price at the time) into
an archive, so history/receipts/tax are independent of later catalog edits.

**Titles reject HTML-special characters.** The admin editor refuses a product title containing
`& < > " '` (`validateProduct`). VK HTML-escapes such characters in its `order_status_change`
payment-callback echo (e.g. `"` → `&quot;`) but computes the notification signature over a different
form, so our callback signature check no longer matches and the purchase silently fails to confirm —
while the `get_item` phase (whose request carries no title) still passes. Use « » guillemets, not
straight quotes.

## 8. Trusted platform signal

The gate (§4) needs a **trusted, unforgeable** platform context on the server. The client is
never the source of truth.

- The platform is a **property of the session**, captured when the session is created. VK and
  Telegram wrappers re-mint (and so re-validate the launch signature — VK launch-params `sign`
  / Telegram `initData`) on **every cold start**, so their platform is re-confirmed each launch;
  a `direct` session captures it once, established by the fact of a web/native session's creation
  (no external signer, and none needed — reaching vk/tg segments in a direct context still
  requires a real attachment, §6).
- The platform carries **kind** (`vk`/`telegram`/`direct`) **plus subtype**
  (`ios`/`android`/`web`). `kind` is always trusted — the server derives it from the validated
  launch, never a client field. The **subtype is trusted only for VK**: it rides inside the
  signed launch parameters, which is what makes the **VK iOS freeze** enforceable; for Telegram
  and direct the subtype is client-reported and best-effort, so the gate never keys off it.
- The gateway resolves the session and passes `platform` to the backend (alongside the existing
  `X-User-ID`), sourced from the session — never the client request body.
- **Fail-closed:** an untrusted platform — a session with no recorded platform, one predating
  this feature or one the gateway could not attribute — denies spends/purchases and applying any
  foreign origin (view only). A VK/TG session recovers on its next cold-start re-mint; a reused
  direct/email session on re-login.

## 9. Payment intake

**Server callback only.** Chips are credited solely on a **verified** provider callback —
YooKassa notification / TG `successful_payment` / VK callback. A client "I paid" is ignored. What
"verified" means differs by rail: VK and Telegram sign their callbacks, and **YooKassa does not**
(D48) — see the confirming read below.

**Single writer.** One payments domain is the only writer of the ledger. Public webhooks
(YooKassa/VK) terminate at the edge (Caddy/gateway) and proxy into payments; TG
`successful_payment` reaches the bot, which forwards into payments. One place credits and
dedupes.

**Order-flow.** The server pre-creates an `order(pending)` with account / platform / pack /
expected amount / origin. The `order_id` is threaded to the provider (YooKassa `metadata.order_id` /
TG `invoice_payload` / VK `item`). The callback matches by `order_id` (never by amount, so
equal-amount collisions cannot happen), verifies the amount, credits, marks `paid`.
**Idempotency:** dedup by `(provider, provider_payment_id)`.

**Direct rail (YooKassa).** Opening a purchase is an outbound API call: the server creates the
payment (`POST /v3/payments`, `capture: true`, redirect confirmation, the order id as both the
`Idempotence-Key` and `metadata.order_id`, plus the fiscal receipt of §12) and sends the customer to
the returned `confirmation_url`. The provider's payment id is recorded on the order straight away,
which is what later lets the order be re-checked and refunded. The browser return page
(`/pay/yookassa/return`) is cosmetic: the credit never rides a redirect.

**The notification is a hint, never evidence (D48).** YooKassa does not sign notifications, so
nothing in the body may be acted on. It only names a payment, which the server then re-reads with
`GET /v3/payments/{id}`; only that answer is trusted. Two guards ride on it: the payment's metadata
must name the order being credited, and its `test` flag must match the shop's, so a test-shop payment
can never credit real chips (nor a live payment be credited against test credentials). The reply
tells the provider whether to redeliver: 200 for anything durably decided, including a duplicate and
a permanent rejection, and 5xx only for a transient failure (YooKassa redelivers for 24 hours).

The sender address is **not** checked (D48 rev). It would add no security — the confirming read is
the whole boundary — and the one thing it bought, keeping a forger from turning each fabricated
notification into an outbound call of ours, is already bought earlier and far more tightly: the order
is resolved from the notification's metadata **before** any provider call, so an id matching no order
costs one indexed read and stops there, and guessing a live order id means guessing a uuid. An
address check is also actively harmful wherever the deployment cannot observe real client addresses —
a contour behind a tunnel sees only its own — where it rejects genuine notifications.

**Reconciliation on a short cadence (D49 rev).** No open-ended polling, but the check is **not** tied
to the order lifetime: that governs when an unpaid order is written off, which answers "how long may
a customer take to pay" — a different question from "how soon should we notice a lost callback".
Tying them together would make a customer wait a full lifetime for chips whenever the notification
path fails. The pending-order reaper instead asks the provider about every pending order older than a
minute that carries a payment id, and credits the ones that were in fact paid. That bounds the calls
one order can cause to its lifetime divided by the sweep interval — a handful — while a failure of
the primary path costs minutes rather than half an hour.

**A declined payment is surfaced.** A YooKassa `payment.canceled` records a `failed` payment event,
so the customer is told the attempt did not go through instead of watching a balance that never
moves. An order simply abandoned records nothing — it just expires, invisibly.

**Pending is invisible** to the user; it auto-expires on a timeout (~30 min, DB hygiene). A
valid callback is **always** honoured, even on an expired order (`expired` ≠ cancellation —
the money is real, the chips are owed). The user sees only successful purchases.

**TG Stars.** Only the **bot** reaches Telegram, so the whole rail funnels through the reverse
mTLS **bot-link** (bot ↔ gateway; the bot cannot dial the backend). The invoice is minted by the
bot: on the order path the gateway sends a `CreateInvoice` command and the bot returns a
`createInvoiceLink` (XTR) in its Ack, which the Mini App opens with `WebApp.openInvoice`. Before any
star moves the bot answers `pre_checkout_query` via a bot→gateway `ValidatePreCheckout` unary
(backed by the intake): approve only if the order exists, is still creditable and is **not already
paid** — a Stars invoice link is reusable, so this gate is the one place a repeat payment is stopped
before the charge; the decline reason is localised to the order account's language.

`successful_payment` reaches the bot only (Bot API, not the Mini App), and the bot host is weak and
can lose connectivity, so the bot is a durable link. Store-and-forward on **SQLite** on the bot's
disk (`internal/outbox`): persist on receipt (idempotent on `telegram_payment_charge_id`) → forward
over the bot-link (a `ForwardPayment` unary; the gateway proxies to the intake) → on a durable
response, mark `forwarded`. Re-drives undelivered on restart and on a periodic tick. At-least-once
delivery + idempotent intake (dedup by `telegram_payment_charge_id`) = credited exactly once.

**Events.** The payments domain writes `payment_events` (succeeded / failed / refunded); a
dispatcher fans out over channels — the live gRPC stream if the user is in-app, else the
existing `botlink` push / email relay. "Payment failed" (an **active** provider decline, not
an abandoned pending) is surfaced to the user; "payment succeeded" is a hook (email / bot
message).

**Refunds.** ToS is **non-refundable** — we do not offer refunds to the user. Refunds are
**admin-triggered** (the E7 console). On the direct rail the console does the whole job in one click
(D50): it calls YooKassa's refund API first (`POST /v3/refunds`, the order id as the
`Idempotence-Key`, carrying the refund receipt of §12) and records the reversal only once the money
has actually moved — a failed call records **nothing**, so the ledger can never claim a refund that
did not happen. A refund is recorded **only in status `succeeded`**: one still `pending` can yet be
canceled, and the ledger is append-only, so recording early could revoke a customer's chips for money
that stayed with us. Pressing again is the way out — the idempotency key returns the same refund
rather than paying twice. The recorded refund id is the provider's own, which keeps the ledger
reconcilable against YooKassa's records.

**The cabinet is a second entry point (D52).** Unlike the earlier rails, YooKassa lets an operator
refund from the merchant cabinet, and such a refund never passes through our API — so the money would
go back while the chips stayed credited. The `refund.succeeded` notification closes that: the refund
is re-read from the API (the body is no more evidence than a payment notification's), bound back to
the order through the payment id we recorded, and reversed through the same engine — idempotent on
`(provider, refund id)`, so the notification for a refund the console already recorded reverses
nothing twice. The engine is **full-refund-only** by design (it revokes exactly what the pack funded
and rejects any other amount), so a **partial** refund is recorded as nothing at all and logged
loudly for an operator: there is no non-arbitrary way to decide how many chips a part-refund costs.

The two recording paths race, benignly: YooKassa fires `refund.succeeded` the moment the refund is
created, so the notification often writes the reversal before the console's own write lands. Both
name the same refund id, so the second is caught by the idempotency index and nothing is revoked
twice; the console reports the refund as successful rather than as a repeated click.

VK refunds are still handled by support and Telegram Stars refunds issued with `refundStarPayment`,
both recorded by hand afterwards. All of them converge on one engine —
the `Refund` method (`internal/payments`): it matches the paid order, appends a **refund** ledger
row (idempotent on `(provider, provider_refund_id)` — the refund id is distinct from the fund's
payment id, so the two rows coexist under the same partial-unique index), and **best-effort revokes
the funded chips floored at 0** (never negative — D27, `balances_chips_chk`). When the chips were
already spent, the unrecoverable remainder is recorded as a per-account **loss + abuse flag**
(`payments.account_risk`, read by the E7 report). The refund ledger row's chip delta is what was
actually reclaimed, so the ledger stays reconcilable against the balance; the **full** reversal
(money, original chips, loss) rides in the row's snapshot. The order stays `paid` — the refund lives
in the ledger + a `refunded` payment event, not in the order status. A duplicate refund reverses
nothing. The ledger is **export-ready** for future tax reporting and reconciliation (the reconciler
itself is not built yet; the schema stays compatible).

## 10. Ads

**Launch scope: VK only** for video (rewarded payout in RUB, ОРД automatic, API ready).
web/native/TG keep the existing house **text banner** only; video is deferred until a
ruble-paying in-app network exists. The ad provider is behind an **abstraction** so a future
network for other platforms slots in without rework. Crypto-payout networks (AdsGram/AdMob)
are rejected — no legal ruble income for a self-employed (НПД) developer.

**Rewarded** (voluntary video for chips) credits chips through payments. **VK Mini App ads expose
only a client-side watch result** (`VKWebAppShowNativeAds` → `data.result`) — there is no
server-to-server verify — so a rewarded credit is **client-attested** (D29 amended: server verify is
not possible on VK). The anti-abuse (and economic) guard is a **server-side daily and hourly cap**
(config `reward_daily_cap` / `reward_hourly_cap`, default 50 / 10), which bounds a forger who skips
the ad and calls the credit endpoint directly and, as importantly, limits free rewarded chips so a
player who wants more **buys**. The credit is idempotent on a client nonce and order-less; the payout
is config (`rewarded_payout_chips`, default 0 = rewarded off until set). Rewarded is VK-only and is
not suppressed by no-ads (D9). A future network that offers a server verify slots in behind the ads
abstraction. On the test contour a build flag (`VITE_ADS_STUB`) swaps a toast for the real ad; prod
always shows real ads (a failed real ad must not credit).

**Interstitial** (fullscreen after a confirmed play), **VK-only**, configurable server-side
values. The gate is **client-mirrored**: the profile carries the cooldowns and a `suppressed`
flag (the same no-ads / `no_banner` gate as the banner, resolved server-side in `adsFor`), and
the client self-gates on a **single shared** last-shown time in `localStorage` — the kind only
picks the required gap, so a hint ad and a move ad never fire within a cooldown of each other
(one shared timer, not one per kind) — no per-move server round-trip. The contour
`VITE_ADS_STUB` swaps the same "ad fired" toast for the real ad. Values:

- Global cooldown **per user, across all games**, default **5 min**.
- **`vs_ai` — 30 min** (aligned with the hint cooldown, so it does not scare casual players).
- Applying a **hint** triggers an interstitial **independently** of the main cooldown, with
  its own **1-min** cooldown.
- Fires **only after a confirmed play or a hint** — never after a pass, exchange or resign
  (an ad for a non-scoring action would only annoy, so those are never "rewarded" with one).
- Offline — banner only.
- Respect VK's own frequency caps.

**No ads offline** beyond the house banner. The `no-ads` benefit suppresses the banner via
the existing `ads.Eligible` (`backend/internal/ads/ads.go`), which is extended to gate on
the **origin benefit applicable in the current context** rather than one global flag.

## 11. Admin, audit, reporting

**Append-only ledger + materialized balance.** The operations ledger is **INSERT-only**
(never UPDATE/DELETE — full audit). Segment balances `(account, source)` and benefits
`(account, origin)` are a fast **materialized** cache, updated **in the same transaction** as
the ledger write, and recomputable from the ledger for reconciliation.

**In-process read cache.** On top of the materialized tables, the payments package keeps an
in-process, account-keyed, write-through cache of each account's segments and benefits, so the
hot read paths — the ad-eligibility check, hint availability, the wallet view, the spend gate
— issue **no** query to the `payments` schema on the steady-state path. It is invalidated on
every payments mutation (spend / grant / fund / refund / merge) and re-read from the
materialized tables on a miss (the same write-through pattern the account-suspension gate
uses). Single-instance, matching the deployment; a multi-instance backend would need a shared
cache. Identity-presence (which segments are awake, §6) is supplied by the caller, not cached
here, so unlink/re-link takes effect immediately.

**Admin rewards.** An admin grants **concrete values only** (no-ads / hints) — **never
chips** (a gifted currency balance = a store cash-desk bypass). It grants either raw atoms or a
**defined value product** (a reward bundle, which may be archived — hidden from the store but
grantable); both refuse a `chips` or `tournament` atom. The admin **picks the
origin** at grant time (compliance is on them: `origin=vk` point-wise/low-volume = low risk,
`origin=direct` = safe). A grant is a ledger transaction of type `admin_grant`, price 0
chips (the by-product grant records the source `product_id` + snapshot) — full audit of rewards.

**The ledger section** `/_gm/ledger` is the all-accounts view of the money: every operation, newest
first, filtered by date range (defaulting to the last 30 days), by **wallet** (`vk`/`telegram`/
`direct` — matching the funded segment or the benefit origin), by **rail** (the settling provider, so
chip spends drop out by construction), by kind and by account. Above the table sit the totals for
**everything the filter matches**, not merely the page: money in and refunded per currency (the rails
settle in roubles, Votes and Stars, so one sum across them would mean nothing) and chips credited and
spent. The row amounts come from the ledger snapshot, since the ledger's own columns count chips.
Paging, the CSV export and a refund's way back all carry the same filter query, so none of them can
silently show a different slice than the screen.

The **refund action** lives on the funded rows here — the operator can find a payment by filter
without knowing whose it is first — and returns to the same filtered view afterwards.

**The user card** carries the account's standing rather than its history: segment balances, benefits,
the refund-risk flag, and a short lifetime summary (money paid and refunded per currency, chips
credited and spent), with a link into the ledger section pre-filtered to that account. One place
renders operations, with filters and paging, instead of two.

## 12. Taxes and compliance

Receipts are automatic **through the provider**, and differ by rail:

- **YooKassa** (direct) — **no receipt is sent, by design (D51 rev)**. The merchant operates on
  **НПД**, which is outside 54-ФЗ: there is no online cash register and the provider registers
  nothing. Each operation is reported by the merchant to **«Мой налог»**, which issues the чек.
  YooKassa does not serve receipts for this regime at all.

  The fiscal code is **kept dormant**, not deleted: «Чеки от ЮKassa» (YooKassa owning the cash
  register, the fiscal drive and the OFD contract) registers a receipt **only if the request carries
  it**, and that request-building lives behind one switch — `BACKEND_YOOKASSA_VAT_CODE`. Unset, no
  `receipt` is built or sent; set to a 54-ФЗ rate code (tag 1199) it goes back to sending one line
  (pack title, quantity 1, amount) with the settlement subject `service` (tag 1212) and method
  `full_payment` (tag 1214), delivered by email to the D36 anchor. That switch exists because the
  return is foreseeable: НПД carries an annual income ceiling, and losing the regime puts 54-ФЗ back
  in force.

  Reporting each rouble operation to «Мой налог» is automated — see below.
- **VK** — VK processes Votes through the tax authority itself; nothing to do.
- **TG Stars** — no tax side (for a RU self-employed, Stars are not legally withdrawable = not
  НПД income; accepted, no receipt issued).

**ОРД** (ad marking) for VK ads is handled on VK's side. (Not legal advice — the owner
confirms the exact НПД scheme with a tax advisor.)

### Reporting to «Мой налог» (D53-D60)

Rouble income taken through the direct rail is registered with the tax service by us, because
nobody else does it: the provider neither files nor issues a receipt under this regime. The rail
covers `kind='fund'`, `provider='yookassa'`, currency `RUB` — the store rails are out of scope,
since the ledger records their price in the store's own currency and holds no rouble amount at all.

**Where it runs.** `backend/internal/mynalog` is the API client (no database), `backend/internal/
mynalogsync` the orchestration, `payments.mynalog_receipt` the per-income progress, and
`/_gm/mynalog` the operator surface. The console button and the background worker call the same
`RunBatch`; there is deliberately no second implementation of the part that decides what a failed
registration means. The whole rail is dormant without `BACKEND_MYNALOG_KEY`.

**The API is unofficial** — `lknpd.nalog.ru`, no published contract, no sandbox. Two consequences
run through the design:

- **Registering an income is not idempotent.** There is no idempotency key, so an error does not
  mean nothing happened. The service name is therefore frozen in the database *before* the call and
  carries a marker taken from the **tail** of the order id (a UUIDv7's leading digits are a
  millisecond clock and would be shared by every order in the same minute). After a failure the
  income list is searched for that exact name: found means filed, not found means **unresolved** —
  which halts the queue until a human decides, because the alternatives are declaring an income
  twice or not at all. One run at a time, on a Postgres advisory lock, for the same reason.
- **Faults are classified, not just logged.** A 401 is renewed silently; a 429 backs off; a 5xx or
  timeout retries later and only alerts after a day; any other 4xx is unfixable by repetition, and
  three in a row take the rail out of service — a changed format must not become thousands of
  requests overnight. Exceeding the annual НПД ceiling is separated out, because it means the regime
  no longer applies.

**Timing.** Every moment is sent in the taxpayer's zone (`BACKEND_MYNALOG_TZ`, default
`Europe/Moscow`), since the offset decides which tax month a near-midnight payment falls into; the
receipt carries the date the money arrived, not the date it was filed. The automatic mode ticks
every 15 minutes and does nothing — including not authenticating — when the queue is empty. A
separate daily watchdog runs **whether or not** the automatic mode does, and escalates unfiled
income from a closed month on the 1st, the 5th and the 9th. (ст. 14 ч. 3 ФЗ-422 allows until the
9th only for settlements *not* involving an electronic means of payment; a card payment is one, so
the receipt is strictly due at settlement. The automatic mode satisfies both readings.)

**Manual fallback.** `/_gm/mynalog.csv` lists exactly what would be sent — time, service name,
amount — plus the ledger id, so a receipt filed by hand can have its number entered back on the
page. That number is what keeps a hand-filed income annullable on a refund, which is why it is
asked for rather than a plain "done" tick.

**Refunds.** The tax service has no refund concept: annulling the receipt *is* the refund. A refund
that lands before the income was ever filed is ruled out locally as `not_required` — nothing filed,
nothing annulled, no call made. A partial refund is out of scope on both sides (§ Refunds).

**The buyer hears about it three times**, in Russian, driven by durable queues rather than by the
payment path: the purchase confirmation (which says plainly that it is *not* the fiscal receipt and
that one follows), the receipt itself with its printable link, and — after a refund — a notice that
the receipt has been annulled. The first rides the existing `payments.payment_events` outbox on its
own `mailed_at` cursor; the other two ride columns on the export row. The address is the D36
confirmed-email anchor a direct purchase already requires.

**Credentials.** The cabinet login and password are typed into the console, used once and never
stored: only the refresh token they yield is kept, sealed with AES-GCM under
`BACKEND_MYNALOG_KEY` (our own random 32 bytes, not a tax-service credential) so it does not travel
in a database dump. A lost key is a nuisance, not a loss — the operator signs in again.

## 13. Distribution (native Android)

- **RuStore** — an external payment gate is allowed (0%); native = clean `direct` context.
- **Google Play** — direct purchases are **hidden**; the Wallet shows a stub ("install the
  RuStore build to make purchases"). Rewarded ads and spending already-earned chips still
  work. Confirm Google's current in-app-currency rules before the GP release.

## 14. Data model (schema `payments`)

The payments domain lives in its **own schema `payments`** in the shared Postgres instance,
with its own DB role (rights limited to `payments`) and a domain package behind a hard
interface. There is **no cross-schema foreign key** to `backend.accounts` — an account id is a
plain value here, kept consistent in code and joined to the tombstoned account /
retained-identities dossier by the stable id. That keeps the chip↔benefit spend atomic
**within `payments`** and the domain extractable into its own database. Durability is **PITR**
(continuous WAL archive), independent of DB topology.

Core tables (final names/columns fixed in `PLAN.md`):

- **ledger** — append-only operations: fund / spend / `admin_grant` / refund; `(provider,
  provider_payment_id)` unique for idempotency; export-ready.
- **balances** — materialized `(account_id, source) → chips`.
- **benefits** — materialized `(account_id, origin)` → no-ads `paid_until`/`forever` +
  hints count.
- **catalog** — atoms + products (soft-deletable), per-method prices, chip-purchase rates,
  rewarded payout.
- **orders** — pending purchases, `order_id`, expected amount, origin, status
  (pending/paid/expired).
- **payment_events** — succeeded/failed/refunded for the dispatcher.

Legacy `accounts.hint_balance` and `accounts.paid_account` are **deprecated** in favour of the
segmented model and dropped in a later **contract-phase** migration (expand-contract, after the
currency core flips reads and Release 2 — image rollback stays DB-safe); neither was ever set in
prod (no purchase flow existed), so legacy values are zeroed.

## 15. Glossary

- **Фишка / chip** — the in-game currency; uniform unit, segmented by `source`.
- **source** — where chips were funded (`vk`/`telegram`/`direct`).
- **origin** — where a value was bought; governs where the benefit applies.
- **value / benefit** — what chips buy (no-ads, hints, tournament fee).
- **gate** — the one-directional store-compliance rule (§4).
- **ledger** — the append-only record of all money/value operations.
- **rail** — a payment provider (YooKassa / VK Votes / TG Stars).