feat(payments): settle the direct rail through YooKassa
CI / changes (pull_request) Successful in 2s
CI / unit (pull_request) Successful in 11s
CI / integration (pull_request) Successful in 25s
CI / ui (pull_request) Successful in 1m17s
CI / conformance (pull_request) Successful in 10s
CI / gate (pull_request) Successful in 0s
CI / deploy (pull_request) Successful in 1m50s
CI / changes (pull_request) Successful in 2s
CI / unit (pull_request) Successful in 11s
CI / integration (pull_request) Successful in 25s
CI / ui (pull_request) Successful in 1m17s
CI / conformance (pull_request) Successful in 10s
CI / gate (pull_request) Successful in 0s
CI / deploy (pull_request) Successful in 1m50s
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.
This commit is contained in:
@@ -241,6 +241,29 @@ The native Android app is a Capacitor 8 wrapper of the `ui` SPA, scaffolded unde
|
||||
|
||||
- **Monetization** — «Фишка» currency, per-platform wallets, ads. Agreements in
|
||||
`docs/PAYMENTS_DECISIONS_ru.md`; a phased plan (E0–E9). go-jet money rule above applies.
|
||||
- **YooKassa (the direct rail since v1.x) does NOT sign its webhooks.** Authenticity is the
|
||||
confirming `GET /v3/payments/{id}` — never the notification body — plus the published sender-IP
|
||||
allowlist. Two extra guards ride on the confirmed object: its `metadata.order_id` must name the
|
||||
order, and its `test` flag must match the shop's `IsTest` (a test-shop payment must never credit
|
||||
real chips). Answer 200 for anything durably decided, 5xx only to be redelivered (YooKassa retries
|
||||
24h).
|
||||
- **YooKassa DOES have a test mode** — a separate *test shop* (own shopId/secret, test cards, up to
|
||||
20 of them), and webhooks/receipts/refunds all work there. The whole rail is verifiable on the
|
||||
contour without real money; don't plan around "no test payments".
|
||||
- **YooKassa has no cabinet-side generic чек.** Unlike Robokassa's cloud kassa, «Чеки от ЮKassa»
|
||||
registers a receipt **only if the request carries `receipt`** — so the itemized receipt is
|
||||
mandatory code on both payment and refund. `payment_subject`/`payment_mode`/`vat_code` are fields
|
||||
*inside* `receipt.items[]` (54-ФЗ tags 1212/1214/1199), documented under the receipts section, not
|
||||
the payment API — easy to miss. A malformed receipt is an API error at payment creation, so it
|
||||
breaks purchases loudly rather than silently skipping the fiscal document.
|
||||
- **The gateway cannot import `backend/internal/*`** (separate module + Go's internal rule), so a
|
||||
security list shared by both hops either lives in `pkg/` or is enforced backend-side. The YooKassa
|
||||
sender allowlist is enforced in the backend, with the gateway forwarding the real peer IP as
|
||||
`X-Forwarded-For` — do not duplicate the CIDR list into the gateway.
|
||||
- **Robokassa is retired but wired.** The direct rail resolves YooKassa → else Robokassa, and no
|
||||
deployment sets the Robokassa credentials. Reviving it is a credentials change, not a code change;
|
||||
`backend/internal/robokassa/README.md` holds the retired vars, cabinet URLs and the known gap
|
||||
(the per-channel `…_WEB_*`/`…_ANDROID_*` vars never reached any workflow).
|
||||
- **VK payment title trap:** a product title with an HTML-special char (`& < > " '`) silently kills
|
||||
VK purchases. VK HTML-escapes it in the `order_status_change` callback echo (`"`→`"`) but
|
||||
signs a different form → the gateway logs `vk callback: bad signature` and rejects it (get_item
|
||||
|
||||
Reference in New Issue
Block a user