feat(payments): VK Votes payment rail

Wire the VK Mini Apps ("голоса") rail end to end, reusing the intake engine. The
wallet.order endpoint branches by rail: a VK context opens a pending order
(provider vk) and returns its id, which the client passes to VKWebAppShowOrderBox.
VK's two-phase payment callback is verified at the gateway with the app protected
key (GATEWAY_VK_APP_SECRET) and proxied to a backend intake handler: get_item
returns the ordered pack's title and vote price; a chargeable order_status_change
credits the vk segment exactly once (the same Fund, idempotent on VK's own order
id) and records a succeeded event, so the dispatcher push refreshes the wallet.
Integration test for the VK order->credit path.

backend/internal/inttest/payments_intake_test.go

@@ -77,6 +77,58 @@ func TestPaymentsOrderFundCreditsOnce(t *testing.T) {
 	}
 }
 
+// TestPaymentsVKOrderFundCredits exercises the VK Votes rail over Postgres: a VK order prices the
+// pack in votes; the get_item lookup returns its title and vote price; a chargeable
+// order_status_change credits the vk segment exactly once (idempotent on VK's own order id).
+func TestPaymentsVKOrderFundCredits(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	acc := uuid.New()
+	prod := seedPackProduct(t, 200, methodPrice{method: "vk", currency: "VOTE", amount: 30})
+
+	res, err := svc.CreateOrder(ctx, acc, payments.NewContext("vk", "web"), []payments.Source{payments.SourceVK}, prod, "vk")
+	if err != nil {
+		t.Fatalf("create vk order: %v", err)
+	}
+	if res.Amount.Currency() != payments.CurrencyVote || res.Amount.Minor() != 30 {
+		t.Fatalf("vk order amount = %s, want 30 VOTE", res.Amount)
+	}
+
+	// get_item phase: title + vote price.
+	title, amount, err := svc.OrderItem(ctx, res.OrderID)
+	if err != nil {
+		t.Fatalf("order item: %v", err)
+	}
+	if title == "" || amount.Minor() != 30 || amount.Currency() != payments.CurrencyVote {
+		t.Errorf("order item = %q / %s, want a title + 30 VOTE", title, amount)
+	}
+
+	// order_status_change phase: VK's own order id is the idempotency key.
+	paid, _ := payments.MoneyFromMinor(30, payments.CurrencyVote)
+	out, err := svc.Fund(ctx, res.OrderID, "vk", "vk-order-777", paid)
+	if err != nil {
+		t.Fatalf("vk fund: %v", err)
+	}
+	if out.AlreadyCredited || out.Chips != 200 || out.Source != payments.SourceVK {
+		t.Fatalf("vk fund outcome = %+v, want 200 chips credited to vk", out)
+	}
+	if got := readBalance(t, acc, "vk"); got != 200 {
+		t.Errorf("vk balance after fund = %d, want 200", got)
+	}
+
+	// A duplicate VK callback (same VK order id) credits nothing more.
+	out2, err := svc.Fund(ctx, res.OrderID, "vk", "vk-order-777", paid)
+	if err != nil {
+		t.Fatalf("duplicate vk fund: %v", err)
+	}
+	if !out2.AlreadyCredited {
+		t.Error("duplicate VK callback not flagged AlreadyCredited")
+	}
+	if got := readBalance(t, acc, "vk"); got != 200 {
+		t.Errorf("vk balance after duplicate = %d, want 200 (credited once)", got)
+	}
+}
+
 // TestPaymentsFundAmountMismatch verifies a callback whose paid amount does not match the order is
 // refused and credits nothing (§9: verify the amount after matching by order id).
 func TestPaymentsFundAmountMismatch(t *testing.T) {

backend/internal/payments/service_intake.go

@@ -52,6 +52,25 @@ func (s *Service) CreateOrder(ctx context.Context, accountID uuid.UUID, cxt Cont
 	return OrderResult{OrderID: orderID, Amount: pack.price, Title: pack.title}, nil
 }
 
+// OrderItem returns a pending order's human title and the amount it charges, in the order's own
+// currency — the details a provider's item-lookup phase needs (VK's get_item). It reads the order
+// and the pack title, honouring the pack even if it was later deactivated (mirrors Fund).
+func (s *Service) OrderItem(ctx context.Context, orderID uuid.UUID) (title string, amount Money, err error) {
+	ord, err := s.store.orderByID(ctx, orderID)
+	if err != nil {
+		return "", Money{}, err
+	}
+	_, title, err = s.store.packForCredit(ctx, ord.productID)
+	if err != nil {
+		return "", Money{}, err
+	}
+	amount, err = MoneyFromMinor(ord.expectedAmount, Currency(ord.currency))
+	if err != nil {
+		return "", Money{}, err
+	}
+	return title, amount, nil
+}
+
 // Fund credits a paid order into its funded segment exactly once, from a verified provider callback
 // — the single writer for every rail. It matches the order, verifies the paid amount, appends the
 // fund ledger row (idempotent on (provider, provider_payment_id)), credits the balance and marks

backend/internal/server/handlers.go

@@ -73,11 +73,16 @@ func (s *Server) registerRoutes() {
 		u.GET("/wallet/catalog", s.handleWalletCatalog)
 		u.POST("/wallet/buy", s.handleWalletBuy)
 	}
-	if s.payments != nil && s.robokassa.MerchantLogin != "" {
-		// Direct-rail (Robokassa): open a pending order (user group), and receive the verified
-		// Result callback the gateway forwards (internal group, gateway-only — the single writer).
+	if s.payments != nil {
+		// The money order endpoint dispatches by rail (direct → Robokassa, vk → VK); an
+		// unsupported or unconfigured rail returns 501 from the handler. The provider callbacks are
+		// gateway-only (the single writer): the VK payment callback (both phases handled here), and
+		// the Robokassa Result callback when a merchant is configured.
 		u.POST("/wallet/order", s.handleWalletOrder)
-		s.internal.POST("/payments/robokassa/result", s.handleRobokassaResult)
+		s.internal.POST("/payments/vk/callback", s.handleVKCallback)
+		if s.robokassa.MerchantLogin != "" {
+			s.internal.POST("/payments/robokassa/result", s.handleRobokassaResult)
+		}
 	}
 	if s.links != nil {
 		// Account linking & merge. The request step always mails a code;

backend/internal/server/handlers_intake.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"net/http"
 	"net/url"
+	"strconv"
 
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
@@ -13,8 +14,11 @@ import (
 	"scrabble/backend/internal/payments"
 )
 
-// providerRobokassa is the ledger/order provider tag for the direct (RUB) rail.
-const providerRobokassa = "robokassa"
+// Ledger/order provider tags per rail.
+const (
+	providerRobokassa = "robokassa" // the direct (RUB) rail
+	providerVK        = "vk"        // the VK Votes rail
+)
 
 // walletOrderRequest is the POST body of a chip-pack purchase: the pack to fund.
 type walletOrderRequest struct {
@@ -52,28 +56,42 @@ func (s *Server) handleWalletOrder(c *gin.Context) {
 		s.abortErr(c, err)
 		return
 	}
-	if cxt.Kind != payments.SourceDirect {
+	switch cxt.Kind {
+	case payments.SourceDirect:
+		if s.robokassa.MerchantLogin == "" {
+			c.AbortWithStatusJSON(http.StatusNotImplemented, errorResponse{Error: errorBody{Code: "rail_unavailable", Message: "this payment method is not available"}})
+			return
+		}
+		// D36: a direct purchase requires a confirmed email anchor.
+		hasEmail, err := s.accounts.HasConfirmedEmail(ctx, uid)
+		if err != nil {
+			s.abortErr(c, err)
+			return
+		}
+		if !hasEmail {
+			c.AbortWithStatusJSON(http.StatusForbidden, errorResponse{Error: errorBody{Code: "email_required", Message: "confirm your email before making a purchase"}})
+			return
+		}
+		res, err := s.payments.CreateOrder(ctx, uid, cxt, present, productID, providerRobokassa)
+		if err != nil {
+			s.abortErr(c, err)
+			return
+		}
+		c.JSON(http.StatusOK, walletOrderResponse{
+			OrderID:     res.OrderID.String(),
+			RedirectURL: s.robokassa.PaymentURL(res.OrderID, res.Amount.Major(), res.Title),
+		})
+	case payments.SourceVK:
+		res, err := s.payments.CreateOrder(ctx, uid, cxt, present, productID, providerVK)
+		if err != nil {
+			s.abortErr(c, err)
+			return
+		}
+		// The client passes the order id to VKWebAppShowOrderBox as the item; there is no redirect.
+		c.JSON(http.StatusOK, walletOrderResponse{OrderID: res.OrderID.String()})
+	default:
 		c.AbortWithStatusJSON(http.StatusNotImplemented, errorResponse{Error: errorBody{Code: "rail_unavailable", Message: "this payment method is not available yet"}})
-		return
 	}
-	hasEmail, err := s.accounts.HasConfirmedEmail(ctx, uid)
-	if err != nil {
-		s.abortErr(c, err)
-		return
-	}
-	if !hasEmail {
-		c.AbortWithStatusJSON(http.StatusForbidden, errorResponse{Error: errorBody{Code: "email_required", Message: "confirm your email before making a purchase"}})
-		return
-	}
-	res, err := s.payments.CreateOrder(ctx, uid, cxt, present, productID, providerRobokassa)
-	if err != nil {
-		s.abortErr(c, err)
-		return
-	}
-	c.JSON(http.StatusOK, walletOrderResponse{
-		OrderID:     res.OrderID.String(),
-		RedirectURL: s.robokassa.PaymentURL(res.OrderID, res.Amount.Major(), res.Title),
-	})
 }
 
 // handleRobokassaResult is the verified Robokassa Result callback, reached only through the gateway
@@ -124,3 +142,86 @@ func (s *Server) handleRobokassaResult(c *gin.Context) {
 	// The gateway echoes response verbatim to Robokassa, which requires the body "OK<InvId>".
 	c.JSON(http.StatusOK, gin.H{"response": "OK" + v.Get("InvId")})
 }
+
+// vkErrorResponse builds VK's error envelope for a payment callback.
+func vkErrorResponse(code int, msg string, critical bool) gin.H {
+	return gin.H{"error": gin.H{"error_code": code, "error_msg": msg, "critical": critical}}
+}
+
+// handleVKCallback is the VK Mini Apps payment callback, reached only through the gateway (which
+// verifies the VK signature and forwards the provider's parameters as a JSON object on the internal
+// route). It answers VK's two phases: get_item returns the ordered pack's title and vote price; a
+// chargeable order_status_change credits the matched order exactly once (idempotent on VK's order
+// id) and records a succeeded event. Both phases use VK's response envelope; the _test variants are
+// the sandbox notifications and are handled identically.
+func (s *Server) handleVKCallback(c *gin.Context) {
+	var params map[string]string
+	if err := c.ShouldBindJSON(&params); err != nil {
+		c.JSON(http.StatusOK, vkErrorResponse(1, "bad request", true))
+		return
+	}
+	ctx := c.Request.Context()
+	switch params["notification_type"] {
+	case "get_item", "get_item_test":
+		orderID, err := uuid.Parse(params["item"])
+		if err != nil {
+			c.JSON(http.StatusOK, vkErrorResponse(20, "item not available", true))
+			return
+		}
+		title, amount, err := s.payments.OrderItem(ctx, orderID)
+		if err != nil {
+			s.log.Warn("vk get_item lookup failed", zap.String("order", orderID.String()), zap.Error(err))
+			c.JSON(http.StatusOK, vkErrorResponse(20, "item not available", true))
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"response": gin.H{
+			"item_id": orderID.String(),
+			"title":   title,
+			"price":   amount.Minor(),
+		}})
+	case "order_status_change", "order_status_change_test":
+		if params["status"] != "chargeable" {
+			c.JSON(http.StatusOK, vkErrorResponse(100, "unsupported status", false))
+			return
+		}
+		orderID, err := uuid.Parse(params["item"])
+		if err != nil {
+			c.JSON(http.StatusOK, vkErrorResponse(20, "item not available", true))
+			return
+		}
+		price, err := strconv.ParseInt(params["item_price"], 10, 64)
+		if err != nil {
+			c.JSON(http.StatusOK, vkErrorResponse(100, "bad price", false))
+			return
+		}
+		paid, err := payments.MoneyFromMinor(price, payments.CurrencyVote)
+		if err != nil {
+			c.JSON(http.StatusOK, vkErrorResponse(100, "bad price", false))
+			return
+		}
+		vkOrderID := params["order_id"]
+		outcome, err := s.payments.Fund(ctx, orderID, providerVK, vkOrderID, paid)
+		if err != nil {
+			if errors.Is(err, payments.ErrOrderNotFound) || errors.Is(err, payments.ErrAmountMismatch) ||
+				errors.Is(err, payments.ErrNotAPack) || errors.Is(err, payments.ErrProductNotFound) {
+				s.log.Warn("vk order rejected", zap.String("order", orderID.String()), zap.Error(err))
+				c.JSON(http.StatusOK, vkErrorResponse(100, "cannot process the order", false))
+				return
+			}
+			s.log.Error("vk fund failed", zap.String("order", orderID.String()), zap.Error(err))
+			c.JSON(http.StatusOK, vkErrorResponse(100, "internal error", false))
+			return
+		}
+		if !outcome.AlreadyCredited {
+			payload, _ := json.Marshal(map[string]any{"chips": outcome.Chips, "source": string(outcome.Source)})
+			if err := s.payments.RecordPaymentEvent(ctx, outcome.AccountID, &orderID, "succeeded", payload); err != nil {
+				s.log.Error("record vk payment event failed", zap.String("order", orderID.String()), zap.Error(err))
+			}
+		}
+		// Echo VK's own order id; app_order_id is optional and our order id is a uuid, so omit it.
+		appOrderID, _ := strconv.ParseInt(vkOrderID, 10, 64)
+		c.JSON(http.StatusOK, gin.H{"response": gin.H{"order_id": appOrderID}})
+	default:
+		c.JSON(http.StatusOK, vkErrorResponse(100, "unknown notification", false))
+	}
+}