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:
@@ -0,0 +1,98 @@
|
||||
package yookassa
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/netip"
|
||||
)
|
||||
|
||||
// Notification events this integration subscribes to. An event name is "<object>.<status>": the
|
||||
// object whose status changed and the status it entered.
|
||||
const (
|
||||
// EventPaymentSucceeded means the money was taken and the order may be credited.
|
||||
EventPaymentSucceeded = "payment.succeeded"
|
||||
// EventPaymentCanceled means the payment was actively declined or abandoned; nothing is credited
|
||||
// and the payer is told the attempt failed.
|
||||
EventPaymentCanceled = "payment.canceled"
|
||||
// EventRefundSucceeded reports a completed refund. Refunds here are always initiated by an
|
||||
// operator through the API, which records them synchronously, so this event is informational.
|
||||
EventRefundSucceeded = "refund.succeeded"
|
||||
)
|
||||
|
||||
// notificationType is the fixed value of a notification envelope's type field.
|
||||
const notificationType = "notification"
|
||||
|
||||
// Notification is an incoming webhook envelope. Object is left raw because its shape depends on the
|
||||
// event — a payment for payment.*, a refund for refund.* — and because nothing in it may be acted on
|
||||
// before GetPayment confirms it: YooKassa does not sign notifications.
|
||||
type Notification struct {
|
||||
Type string `json:"type"`
|
||||
Event string `json:"event"`
|
||||
Object json.RawMessage `json:"object"`
|
||||
}
|
||||
|
||||
// ParseNotification decodes a webhook body and checks the envelope is a notification with an event.
|
||||
// It deliberately validates nothing else: the body is untrusted input whose only job is to name an
|
||||
// object to re-read from the API.
|
||||
func ParseNotification(body []byte) (Notification, error) {
|
||||
var n Notification
|
||||
if err := json.Unmarshal(body, &n); err != nil {
|
||||
return Notification{}, fmt.Errorf("yookassa: decode notification: %w", err)
|
||||
}
|
||||
if n.Type != notificationType || n.Event == "" {
|
||||
return Notification{}, fmt.Errorf("yookassa: not a notification envelope (type %q, event %q)", n.Type, n.Event)
|
||||
}
|
||||
return n, nil
|
||||
}
|
||||
|
||||
// Payment decodes the notification's object as a payment. Use it only for payment.* events; it
|
||||
// yields the payment id to re-read, never the payment state to act on.
|
||||
func (n Notification) Payment() (Payment, error) {
|
||||
var p Payment
|
||||
if err := json.Unmarshal(n.Object, &p); err != nil {
|
||||
return Payment{}, fmt.Errorf("yookassa: decode notification payment: %w", err)
|
||||
}
|
||||
if p.ID == "" {
|
||||
return Payment{}, fmt.Errorf("yookassa: notification payment has no id")
|
||||
}
|
||||
return p, nil
|
||||
}
|
||||
|
||||
// senderPrefixes are the address ranges YooKassa delivers notifications from
|
||||
// (https://yookassa.ru/developers/using-api/webhooks). Single addresses are expressed as /32 and
|
||||
// /128 prefixes. The list is defence in depth only — the confirming GetPayment is what actually
|
||||
// establishes authenticity — so it is kept deliberately literal and easy to audit against the docs.
|
||||
var senderPrefixes = []netip.Prefix{
|
||||
netip.MustParsePrefix("185.71.76.0/27"),
|
||||
netip.MustParsePrefix("185.71.77.0/27"),
|
||||
netip.MustParsePrefix("77.75.153.0/25"),
|
||||
netip.MustParsePrefix("77.75.156.11/32"),
|
||||
netip.MustParsePrefix("77.75.156.35/32"),
|
||||
netip.MustParsePrefix("77.75.154.128/25"),
|
||||
netip.MustParsePrefix("2a02:5180::/32"),
|
||||
}
|
||||
|
||||
// AllowedIP reports whether addr is one of YooKassa's notification senders. An IPv4-mapped IPv6
|
||||
// address is unmapped first, so a dual-stack listener's view of an IPv4 sender still matches.
|
||||
func AllowedIP(addr netip.Addr) bool {
|
||||
addr = addr.Unmap()
|
||||
if !addr.IsValid() {
|
||||
return false
|
||||
}
|
||||
for _, p := range senderPrefixes {
|
||||
if p.Contains(addr) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// AllowedSender reports whether the textual address ip is one of YooKassa's notification senders. An
|
||||
// unparseable address is not allowed.
|
||||
func AllowedSender(ip string) bool {
|
||||
addr, err := netip.ParseAddr(ip)
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
return AllowedIP(addr)
|
||||
}
|
||||
Reference in New Issue
Block a user