@aepstore-dev/contracts 1.63.0 → 1.64.0

package/proto/payments.proto

@@ -1,516 +1,516 @@
-syntax = "proto3";
-
-package payments.v1;
-
-// Commerce + double-entry wallet/ledger (D9 / D9.2). See payments-service/docs/FINANCE.md.
-// Money = Decimal-as-string (D7). Statuses/enums as strings (avoid proto enum
-// value-name clashes within one package).
-service PaymentsService {
-    // ----- buyer -----
-    rpc Topup(TopupRequest) returns (CheckoutResponse);
-    rpc CreateCheckout(CreateCheckoutRequest) returns (CheckoutResponse);
-    rpc GetMyPurchases(GetMyPurchasesRequest) returns (PurchasesListResponse);
-    rpc GetPurchase(GetPurchaseRequest) returns (Purchase);
-    rpc RefundPurchase(RefundPurchaseRequest) returns (Purchase);
-
-    // ----- wallet -----
-    rpc GetWallet(GetWalletRequest) returns (WalletResponse);
-    rpc ListTransactions(ListTransactionsRequest) returns (TransactionsListResponse);
-    rpc GetTransactionMonths(GetTransactionMonthsRequest) returns (GetTransactionMonthsResponse);
-
-    // ----- withdrawals -----
-    rpc RequestWithdrawal(RequestWithdrawalRequest) returns (Withdrawal);
-    rpc ListWithdrawals(ListWithdrawalsRequest) returns (WithdrawalsListResponse);
-    rpc ProcessWithdrawal(ProcessWithdrawalRequest) returns (Withdrawal);
-
-    // ----- provider webhook (gateway forwards a verified event) -----
-    rpc HandlePaymentEvent(PaymentEventRequest) returns (Ok);
-    // Generalized per-provider callback (POST /payments/webhook/:provider).
-    // Carries the EXACT raw JSON body: signed providers (Heleket) hash the
-    // byte-exact payload, so re-serializing a parsed body would break the sign.
-    rpc HandleProviderCallback(ProviderCallbackRequest) returns (Ok);
-
-    // ----- premium -----
-    rpc GetPremiumPlans(GetPremiumPlansRequest) returns (PremiumPlansResponse);
-    rpc PurchasePremium(PurchasePremiumRequest) returns (PurchasePremiumResponse);
-    rpc SetPremiumPaymentMethod(SetPremiumPaymentMethodRequest) returns (PremiumPaymentMethodResponse);
-    // 7-day refund window from completedAt. Reverses ledger, calls YooKassa for
-    // card purchases, rolls back the subscription's expiresAt by the period.
-    rpc RefundPremium(RefundPremiumRequest) returns (RefundPremiumResponse);
-    rpc GetMyPremiumPayments(GetMyPremiumPaymentsRequest) returns (PremiumPaymentsListResponse);
-    rpc GetPremiumPayment(GetPremiumPaymentRequest) returns (PremiumPaymentRow);
-    // Internal — InternalServiceGuard. tasks-service cron triggers due renewals;
-    // payments-service iterates ACTIVE subscriptions with autoRenew+savedCard.
-    rpc RunPremiumRenewals(RunPremiumRenewalsRequest) returns (RunPremiumRenewalsResponse);
-
-    // ----- saved cards -----
-    rpc ListSavedCards(ListSavedCardsRequest) returns (ListSavedCardsResponse);
-    rpc DeleteSavedCard(DeleteSavedCardRequest) returns (Ok);
-    rpc SetDefaultSavedCard(SetDefaultSavedCardRequest) returns (SavedCard);
-    rpc UpdateSavedCard(UpdateSavedCardRequest) returns (SavedCard);
-    // Standalone "bind card" flow: creates a 1₽ YooKassa charge with
-    // save_payment_method=true; after the webhook the SavedCard row is
-    // persisted and the 1₽ credits USER_SPENDING so the user keeps it.
-    rpc BindCard(BindCardRequest) returns (CheckoutResponse);
-    // Poll an intent after returnUrl redirect: TOPUP/PREMIUM completion, bind-card
-    // completion. Ownership-checked by user_id.
-    rpc GetPaymentIntent(GetPaymentIntentRequest) returns (PaymentIntentStatus);
-
-    // ----- FX / available methods (public, cached) -----
-    // Daily CBR rates (RUB base). Frontend uses this for the "≈" display hint;
-    // the authoritative charge amount is always computed server-side at checkout.
-    rpc GetRates(GetRatesRequest) returns (GetRatesResponse);
-    // Payment methods derived from live provider capabilities — the client
-    // renders only what is actually available (e.g. CRYPTO appears once the
-    // Heleket merchant is configured).
-    rpc GetPaymentMethods(GetPaymentMethodsRequest) returns (GetPaymentMethodsResponse);
-
-    // ----- payout details -----
-    rpc UpdatePayoutDetails(UpdatePayoutDetailsRequest) returns (UpdatePayoutDetailsResponse);
-    rpc GetPayoutDetails(GetPayoutDetailsRequest) returns (UpdatePayoutDetailsResponse);
-
-    // ----- admin -----
-    rpc GetAdminOverview(AdminOverviewRequest) returns (AdminOverviewResponse);
-    rpc AdminListTransactions(AdminListTransactionsRequest) returns (AdminTransactionsListResponse);
-    rpc GetUserFinance(GetUserFinanceRequest) returns (UserFinanceResponse);
-    rpc CreateAdjustment(CreateAdjustmentRequest) returns (Ok);
-    rpc GetSalesAnalytics(SalesAnalyticsRequest) returns (SalesAnalyticsResponse);
-}
-
-message Ok { bool ok = 1; }
-
-// ---------------------------------------------------------------------------
-// Purchase / checkout / topup
-// ---------------------------------------------------------------------------
-message Purchase {
-    string id = 1;
-    string product_id = 2;
-    string product_name = 3;
-    string user_id = 4;
-    string price = 5;              // settled RUB amount
-    string status = 6;             // PENDING | COMPLETED | FAILED | REFUNDED
-    string payment_id = 7;
-    string payment_method = 8;     // BALANCE | YOOKASSA | CRYPTO
-    string commission_percent = 9;
-    string seller_amount = 10;
-    string created_at = 11;
-    string completed_at = 12;
-    // FX snapshot at checkout (empty for legacy RUB purchases).
-    string listing_currency = 13;  // RUB | USD | EUR
-    string listing_price = 14;     // Decimal as string, in listing_currency
-    string fx_rate = 15;           // listing→RUB rate used (Decimal as string)
-}
-
-message TopupRequest {
-    string user_id = 1;
-    string amount = 2;       // >= 10.00
-    string return_url = 3;
-    string payment_method = 4; // YOOKASSA | SAVED_CARD | CRYPTO (default YOOKASSA)
-    string saved_card_id = 5;  // required when payment_method=SAVED_CARD
-}
-
-message CreateCheckoutRequest {
-    string user_id = 1;
-    string product_id = 2;
-    string payment_method = 3; // BALANCE | YOOKASSA | SAVED_CARD | CRYPTO (default YOOKASSA)
-    string return_url = 4;
-    // When payment_method=SAVED_CARD — required. ID of a SavedCard row owned
-    // by user_id. Ignored otherwise.
-    string saved_card_id = 5;
-    // When payment_method=YOOKASSA — optional. If true, save the card token
-    // after success; the bound card becomes available in /account/cards.
-    bool save_payment_method = 6;
-}
-
-message BindCardRequest {
-    string user_id = 1;
-    string return_url = 2;
-}
-
-message GetPaymentIntentRequest {
-    string intent_id = 1;
-    string user_id = 2; // ownership check
-}
-
-message PaymentIntentStatus {
-    string id = 1;
-    string user_id = 2;
-    string purpose = 3;          // TOPUP | PREMIUM
-    string status = 4;           // PENDING | COMPLETED | FAILED | CANCELED
-    string amount = 5;
-    string currency = 6;
-    string purchase_id = 7;      // set when purpose=PREMIUM (else empty)
-    string created_at = 8;
-    string updated_at = 9;
-}
-
-message CheckoutResponse {
-    string purchase_id = 1;
-    string payment_id = 2;
-    string confirmation_url = 3; // empty when paid from balance (instant)
-    string status = 4;           // PENDING (redirect) | COMPLETED (balance)
-    string intent_id = 5;        // poll via GetPaymentIntent for TOPUP / bind-card flows
-}
-
-message GetMyPurchasesRequest { string user_id = 1; int32 page = 2; int32 limit = 3; }
-message PurchasesListResponse { repeated Purchase items = 1; int32 total = 2; int32 page = 3; int32 limit = 4; }
-message GetPurchaseRequest { string id = 1; string user_id = 2; }
-message RefundPurchaseRequest { string purchase_id = 1; string actor_user_id = 2; bool is_admin = 3; string reason = 4; }
-
-// ---------------------------------------------------------------------------
-// Wallet & statement
-// ---------------------------------------------------------------------------
-message GetWalletRequest { string user_id = 1; }
-message WalletResponse {
-    string spending = 1;
-    string pending = 2;
-    string payout = 3;
-    string spendable = 4;   // spending + payout
-    string withdrawable = 5; // payout
-    string currency = 6;
-    int32 lifetime_sales = 7;
-    string current_commission_percent = 8;
-}
-
-message ListTransactionsRequest {
-    string user_id = 1;
-    // Legacy low-level filter (one of LedgerTxType). Kept for backward
-    // compatibility — admin tooling still uses it directly.
-    string type = 2;
-    int32 page = 3;
-    int32 limit = 4;
-    // ↓ added for the wallet statement page (Round 3)
-    // UI-semantic filter mapped onto displayKind:
-    //   ALL | SALES | INCOME | OUTCOME | REFUND | WITHDRAWAL | PREMIUM
-    // SALES = the seller's earnings on this account (USER_PENDING credits from
-    // PURCHASE transactions); these stay separate from INCOME (TOPUP).
-    string flow = 5;
-    // Period selection. `month` is the convenience form (YYYY-MM) used by the
-    // month dropdown; from/to override it for an arbitrary range.
-    string month = 6;
-    string from = 7;
-    string to = 8;
-    // Filter wallet to purchases/refunds of a specific Product category. Has
-    // no effect on TOPUP/WITHDRAWAL/PREMIUM/ADJUSTMENT entries (they have no
-    // product).
-    string product_category_id = 9;
-    // sort_by ∈ { date | amount | type }. Default: date.
-    string sort_by = 10;
-    // order ∈ { asc | desc }. Default: desc.
-    string order = 11;
-}
-message StatementEntry {
-    string id = 1;
-    string tx_id = 2;
-    string type = 3;          // raw tx type (TOPUP|PURCHASE|...)
-    string account_kind = 4;
-    string direction = 5;     // DEBIT | CREDIT
-    string amount = 6;
-    string description = 7;
-    string created_at = 8;
-    // ↓ added for the wallet statement page (Round 3)
-    // UI-friendly classification computed server-side:
-    //   TOPUP | PURCHASE | SALE | REFUND | PREMIUM | WITHDRAWAL | ADJUSTMENT
-    // SALE is the seller's view of someone else's PURCHASE (CREDIT to their
-    // USER_PENDING) — distinct from PURCHASE which is the buyer's DEBIT.
-    // PREMIUM is split out of PURCHASE/REFUND so the UI can show
-    // "Продление Premium" / refund-of-premium in their own filter bucket.
-    // SALE_CLEAR transactions are excluded from the wallet view — the maturity
-    // event is surfaced via sale_status on the original SALE row instead.
-    string display_kind = 9;
-    string balance_after = 10;       // affected-account running balance, Decimal-as-string
-    string product_id = 11;          // empty for non-product entries
-    string product_name = 12;
-    string product_category = 13;    // "Assets" | "Project File" | "Templates"
-    string product_preview = 14;     // optional thumbnail URL for richer rows
-    // Sale lifecycle. Populated only when display_kind=SALE.
-    //   PENDING — held in USER_PENDING, not yet withdrawable.
-    //   MATURED — SALE_CLEAR has fired; money is in USER_PAYOUT.
-    string sale_status = 15;
-    // ISO 8601 when the sale becomes withdrawable (sale_completed_at +
-    // GRACE_DAYS). Empty for non-sale rows.
-    string matures_at = 16;
-}
-message TransactionsListResponse { repeated StatementEntry items = 1; int32 total = 2; int32 page = 3; int32 limit = 4; }
-
-message GetTransactionMonthsRequest { string user_id = 1; }
-message GetTransactionMonthsResponse {
-    // Newest first. "YYYY-MM" strings; the dropdown renders them
-    // localized client-side.
-    repeated string months = 1;
-}
-
-// ---------------------------------------------------------------------------
-// Withdrawals
-// ---------------------------------------------------------------------------
-message Withdrawal {
-    string id = 1;
-    string seller_id = 2;
-    string amount = 3;
-    string status = 4;     // PENDING | PROCESSING | COMPLETED | REJECTED
-    string method = 5;
-    string details = 6;
-    string comment = 7;
-    string processed_by = 8;
-    string processed_at = 9;
-    string created_at = 10;
-}
-message RequestWithdrawalRequest { string seller_id = 1; string amount = 2; string method = 3; string details = 4; }
-message ListWithdrawalsRequest { string seller_id = 1; string status = 2; int32 page = 3; int32 limit = 4; }
-message WithdrawalsListResponse { repeated Withdrawal items = 1; int32 total = 2; int32 page = 3; int32 limit = 4; }
-message ProcessWithdrawalRequest { string withdrawal_id = 1; string admin_id = 2; string action = 3; string comment = 4; }
-
-// ---------------------------------------------------------------------------
-// Webhook
-// ---------------------------------------------------------------------------
-message PaymentEventRequest { string event = 1; string payment_id = 2; }
-
-message ProviderCallbackRequest {
-    string provider = 1; // yookassa | heleket | …
-    string raw_body = 2; // exact raw JSON body as received (signature input)
-}
-
-// ---------------------------------------------------------------------------
-// FX rates / payment methods
-// ---------------------------------------------------------------------------
-message GetRatesRequest {}
-
-message FxRate {
-    string currency = 1; // USD | EUR
-    string rate = 2;     // RUB per 1 unit, Decimal as string
-}
-
-message GetRatesResponse {
-    string base = 1;  // always RUB
-    string as_of = 2; // YYYY-MM-DD the rates are for
-    repeated FxRate rates = 3;
-}
-
-message GetPaymentMethodsRequest {}
-
-message PaymentMethodInfo {
-    string method = 1;             // YOOKASSA | SAVED_CARD | CRYPTO | BALANCE
-    string provider = 2;           // yookassa | heleket | '' (BALANCE)
-    repeated string currencies = 3;
-}
-
-message GetPaymentMethodsResponse {
-    repeated PaymentMethodInfo methods = 1;
-}
-
-// ---------------------------------------------------------------------------
-// Admin
-// ---------------------------------------------------------------------------
-message AdminOverviewRequest { string from = 1; string to = 2; }
-message AdminOverviewResponse {
-    string revenue = 1;          // platform commission earned (period)
-    string gmv = 2;              // gross merchandise value (period)
-    string liabilities = 3;      // Σ all users' (pending+payout+spending) — what we owe
-    string psp_clearing = 4;     // money in transit at PSP
-    string payouts_payable = 5;  // reserved for approved withdrawals
-    string refunds_total = 6;
-    string topups_total = 7;
-    string withdrawals_total = 8;
-    int32 sales_count = 9;
-    string currency = 10;
-}
-
-message AdminListTransactionsRequest {
-    string type = 1;
-    string user_id = 2;
-    string account_kind = 3;
-    string from = 4;
-    string to = 5;
-    int32 page = 6;
-    int32 limit = 7;
-}
-message AdminEntry { string account_id = 1; string account_kind = 2; string owner_id = 3; string direction = 4; string amount = 5; }
-message AdminLedgerTx {
-    string id = 1;
-    string type = 2;
-    string status = 3;
-    string ref_type = 4;
-    string ref_id = 5;
-    string description = 6;
-    string created_by = 7;
-    string created_at = 8;
-    repeated AdminEntry entries = 9;
-}
-message AdminTransactionsListResponse { repeated AdminLedgerTx items = 1; int32 total = 2; int32 page = 3; int32 limit = 4; }
-
-message GetUserFinanceRequest { string user_id = 1; }
-message AccountBalance { string kind = 1; string balance = 2; string currency = 3; }
-message UserFinanceResponse {
-    WalletResponse wallet = 1;
-    repeated AccountBalance accounts = 2;
-    repeated StatementEntry recent = 3;
-}
-
-message CreateAdjustmentRequest {
-    string admin_id = 1;
-    string user_id = 2;
-    string account_kind = 3; // USER_SPENDING | USER_PAYOUT | USER_PENDING
-    string direction = 4;    // CREDIT (give) | DEBIT (take)
-    string amount = 5;
-    string reason = 6;
-}
-
-message SalesAnalyticsRequest { string from = 1; string to = 2; string granularity = 3; } // day|week|month
-message SalesPoint { string date = 1; int32 sales_count = 2; string gmv = 3; string revenue = 4; }
-message SellerStat { string seller_id = 1; string username = 2; int32 sales = 3; string gmv = 4; }
-message SalesAnalyticsResponse {
-    repeated SalesPoint points = 1;
-    repeated SellerStat top_sellers = 2;
-    string refund_rate = 3; // % refunded purchases
-}
-
-// ---------------------------------------------------------------------------
-// Premium
-// ---------------------------------------------------------------------------
-message GetPremiumPlansRequest {}
-
-// One plan per (period). Prices are computed server-side from BASE_PRICE × months
-// × (1 − discount); kept here as canonical strings so the gateway has no math.
-message PremiumPlan {
-    string period = 1;          // MONTH_1 | MONTH_3 | MONTH_6 | MONTH_12
-    int32 months = 2;
-    string price = 3;           // total to charge, Decimal-as-string
-    string monthly_price = 4;   // for UI "≈ X ₽/month"
-    string discount_percent = 5;
-    string currency = 6;
-}
-
-message PremiumPlansResponse {
-    repeated PremiumPlan plans = 1;
-    string base_monthly_price = 2;
-}
-
-message PurchasePremiumRequest {
-    string user_id = 1;
-    string period = 2;           // MONTH_1 | MONTH_3 | MONTH_6 | MONTH_12
-    string payment_method = 3;   // BALANCE | YOOKASSA | SAVED_CARD (empty = smart default)
-    string return_url = 4;       // YooKassa only
-    // Save the YooKassa payment_method for future auto-renewals. Ignored for
-    // BALANCE. Kept for backwards compatibility; auto_renew=true implies save.
-    bool save_payment_method = 5;
-    bool auto_renew = 6;         // default false; requires off-session-capable method
-    string saved_card_id = 7;    // optional for SAVED_CARD; empty = default card
-}
-
-message PurchasePremiumResponse {
-    string payment_id = 1;       // PremiumPayment.id
-    string confirmation_url = 2; // empty for BALANCE (instant) or YooKassa-issued
-    string status = 3;           // PENDING (redirect) | COMPLETED (balance)
-}
-
-message RunPremiumRenewalsRequest {
-    int32 max_batch = 1;         // safety cap; default 100
-}
-
-message RunPremiumRenewalsResponse {
-    int32 attempted = 1;
-    int32 succeeded = 2;
-    int32 failed = 3;
-}
-
-message SetPremiumPaymentMethodRequest {
-    string user_id = 1;
-    string method = 2;           // BALANCE | YOOKASSA | SAVED_CARD
-    string saved_card_id = 3;    // optional for SAVED_CARD; empty = default card
-}
-
-message PremiumPaymentMethodResponse {
-    string method = 1;           // BALANCE | YOOKASSA | SAVED_CARD
-    string saved_card_id = 2;    // empty unless SAVED_CARD
-    bool auto_renew = 3;
-}
-
-message PremiumPaymentRow {
-    string id = 1;
-    string user_id = 2;
-    string amount = 3;
-    string period = 4;          // MONTH_1 | MONTH_3 | MONTH_6 | MONTH_12
-    string method = 5;          // BALANCE | YOOKASSA
-    string status = 6;          // PENDING | COMPLETED | FAILED | REFUNDED
-    bool is_renewal = 7;
-    string created_at = 8;
-    string completed_at = 9;
-    string refunded_at = 10;
-    string refunded_amount = 11;
-    // Convenience: true if this payment is currently inside the 7-day refund
-    // window AND status == COMPLETED AND not already refunded.
-    bool refundable = 12;
-}
-
-message RefundPremiumRequest {
-    string user_id = 1;
-    string payment_id = 2;
-    string reason = 3;          // optional
-}
-
-message RefundPremiumResponse {
-    PremiumPaymentRow payment = 1;
-    string new_expires_at = 2;  // ISO 8601 after rollback
-    bool subscription_revoked = 3; // true when rollback put expiresAt <= now
-}
-
-message GetMyPremiumPaymentsRequest {
-    string user_id = 1;
-    int32 page = 2;
-    int32 limit = 3;
-}
-
-message GetPremiumPaymentRequest {
-    string user_id = 1;
-    string payment_id = 2;
-}
-
-message PremiumPaymentsListResponse {
-    repeated PremiumPaymentRow items = 1;
-    int32 total = 2;
-    int32 page = 3;
-    int32 limit = 4;
-}
-
-// ---------------------------------------------------------------------------
-// Saved cards (YooKassa payment_method tokens; we never see PAN)
-// ---------------------------------------------------------------------------
-message SavedCard {
-    string id = 1;
-    string brand = 2;       // "MIR" | "VISA" | "MASTERCARD" | ""
-    string last4 = 3;       // "0000" etc, display-only
-    int32 exp_month = 4;
-    int32 exp_year = 5;
-    bool is_default = 6;
-    string nickname = 7;    // user-set label
-    string created_at = 8;
-}
-
-message ListSavedCardsRequest { string user_id = 1; }
-message ListSavedCardsResponse { repeated SavedCard items = 1; }
-
-message DeleteSavedCardRequest { string user_id = 1; string id = 2; }
-
-message SetDefaultSavedCardRequest { string user_id = 1; string id = 2; }
-
-message UpdateSavedCardRequest {
-    string user_id = 1;
-    string id = 2;
-    string nickname = 3; // empty = clear
-}
-
-// ---------------------------------------------------------------------------
-// Payout details (persistent default; per-withdrawal override still allowed)
-// ---------------------------------------------------------------------------
-message UpdatePayoutDetailsRequest {
-    string user_id = 1;
-    string method = 2;  // "card" | "sbp" | "bank" | "" (clear)
-    string details = 3; // JSON string — payments-service treats opaquely
-}
-
-message UpdatePayoutDetailsResponse {
-    string method = 1;
-    string details = 2;
-}
-
-message GetPayoutDetailsRequest { string user_id = 1; }
+syntax = "proto3";
+
+package payments.v1;
+
+// Commerce + double-entry wallet/ledger (D9 / D9.2). See payments-service/docs/FINANCE.md.
+// Money = Decimal-as-string (D7). Statuses/enums as strings (avoid proto enum
+// value-name clashes within one package).
+service PaymentsService {
+    // ----- buyer -----
+    rpc Topup(TopupRequest) returns (CheckoutResponse);
+    rpc CreateCheckout(CreateCheckoutRequest) returns (CheckoutResponse);
+    rpc GetMyPurchases(GetMyPurchasesRequest) returns (PurchasesListResponse);
+    rpc GetPurchase(GetPurchaseRequest) returns (Purchase);
+    rpc RefundPurchase(RefundPurchaseRequest) returns (Purchase);
+
+    // ----- wallet -----
+    rpc GetWallet(GetWalletRequest) returns (WalletResponse);
+    rpc ListTransactions(ListTransactionsRequest) returns (TransactionsListResponse);
+    rpc GetTransactionMonths(GetTransactionMonthsRequest) returns (GetTransactionMonthsResponse);
+
+    // ----- withdrawals -----
+    rpc RequestWithdrawal(RequestWithdrawalRequest) returns (Withdrawal);
+    rpc ListWithdrawals(ListWithdrawalsRequest) returns (WithdrawalsListResponse);
+    rpc ProcessWithdrawal(ProcessWithdrawalRequest) returns (Withdrawal);
+
+    // ----- provider webhook (gateway forwards a verified event) -----
+    rpc HandlePaymentEvent(PaymentEventRequest) returns (Ok);
+    // Generalized per-provider callback (POST /payments/webhook/:provider).
+    // Carries the EXACT raw JSON body: signed providers (Heleket) hash the
+    // byte-exact payload, so re-serializing a parsed body would break the sign.
+    rpc HandleProviderCallback(ProviderCallbackRequest) returns (Ok);
+
+    // ----- premium -----
+    rpc GetPremiumPlans(GetPremiumPlansRequest) returns (PremiumPlansResponse);
+    rpc PurchasePremium(PurchasePremiumRequest) returns (PurchasePremiumResponse);
+    rpc SetPremiumPaymentMethod(SetPremiumPaymentMethodRequest) returns (PremiumPaymentMethodResponse);
+    // 7-day refund window from completedAt. Reverses ledger, calls YooKassa for
+    // card purchases, rolls back the subscription's expiresAt by the period.
+    rpc RefundPremium(RefundPremiumRequest) returns (RefundPremiumResponse);
+    rpc GetMyPremiumPayments(GetMyPremiumPaymentsRequest) returns (PremiumPaymentsListResponse);
+    rpc GetPremiumPayment(GetPremiumPaymentRequest) returns (PremiumPaymentRow);
+    // Internal — InternalServiceGuard. tasks-service cron triggers due renewals;
+    // payments-service iterates ACTIVE subscriptions with autoRenew+savedCard.
+    rpc RunPremiumRenewals(RunPremiumRenewalsRequest) returns (RunPremiumRenewalsResponse);
+
+    // ----- saved cards -----
+    rpc ListSavedCards(ListSavedCardsRequest) returns (ListSavedCardsResponse);
+    rpc DeleteSavedCard(DeleteSavedCardRequest) returns (Ok);
+    rpc SetDefaultSavedCard(SetDefaultSavedCardRequest) returns (SavedCard);
+    rpc UpdateSavedCard(UpdateSavedCardRequest) returns (SavedCard);
+    // Standalone "bind card" flow: creates a 1₽ YooKassa charge with
+    // save_payment_method=true; after the webhook the SavedCard row is
+    // persisted and the 1₽ credits USER_SPENDING so the user keeps it.
+    rpc BindCard(BindCardRequest) returns (CheckoutResponse);
+    // Poll an intent after returnUrl redirect: TOPUP/PREMIUM completion, bind-card
+    // completion. Ownership-checked by user_id.
+    rpc GetPaymentIntent(GetPaymentIntentRequest) returns (PaymentIntentStatus);
+
+    // ----- FX / available methods (public, cached) -----
+    // Daily CBR rates (RUB base). Frontend uses this for the "≈" display hint;
+    // the authoritative charge amount is always computed server-side at checkout.
+    rpc GetRates(GetRatesRequest) returns (GetRatesResponse);
+    // Payment methods derived from live provider capabilities — the client
+    // renders only what is actually available (e.g. CRYPTO appears once the
+    // Heleket merchant is configured).
+    rpc GetPaymentMethods(GetPaymentMethodsRequest) returns (GetPaymentMethodsResponse);
+
+    // ----- payout details -----
+    rpc UpdatePayoutDetails(UpdatePayoutDetailsRequest) returns (UpdatePayoutDetailsResponse);
+    rpc GetPayoutDetails(GetPayoutDetailsRequest) returns (UpdatePayoutDetailsResponse);
+
+    // ----- admin -----
+    rpc GetAdminOverview(AdminOverviewRequest) returns (AdminOverviewResponse);
+    rpc AdminListTransactions(AdminListTransactionsRequest) returns (AdminTransactionsListResponse);
+    rpc GetUserFinance(GetUserFinanceRequest) returns (UserFinanceResponse);
+    rpc CreateAdjustment(CreateAdjustmentRequest) returns (Ok);
+    rpc GetSalesAnalytics(SalesAnalyticsRequest) returns (SalesAnalyticsResponse);
+}
+
+message Ok { bool ok = 1; }
+
+// ---------------------------------------------------------------------------
+// Purchase / checkout / topup
+// ---------------------------------------------------------------------------
+message Purchase {
+    string id = 1;
+    string product_id = 2;
+    string product_name = 3;
+    string user_id = 4;
+    string price = 5;              // settled RUB amount
+    string status = 6;             // PENDING | COMPLETED | FAILED | REFUNDED
+    string payment_id = 7;
+    string payment_method = 8;     // BALANCE | YOOKASSA | CRYPTO
+    string commission_percent = 9;
+    string seller_amount = 10;
+    string created_at = 11;
+    string completed_at = 12;
+    // FX snapshot at checkout (empty for legacy RUB purchases).
+    string listing_currency = 13;  // RUB | USD | EUR
+    string listing_price = 14;     // Decimal as string, in listing_currency
+    string fx_rate = 15;           // listing→RUB rate used (Decimal as string)
+}
+
+message TopupRequest {
+    string user_id = 1;
+    string amount = 2;       // >= 10.00
+    string return_url = 3;
+    string payment_method = 4; // YOOKASSA | SAVED_CARD | CRYPTO (default YOOKASSA)
+    string saved_card_id = 5;  // required when payment_method=SAVED_CARD
+}
+
+message CreateCheckoutRequest {
+    string user_id = 1;
+    string product_id = 2;
+    string payment_method = 3; // BALANCE | YOOKASSA | SAVED_CARD | CRYPTO (default YOOKASSA)
+    string return_url = 4;
+    // When payment_method=SAVED_CARD — required. ID of a SavedCard row owned
+    // by user_id. Ignored otherwise.
+    string saved_card_id = 5;
+    // When payment_method=YOOKASSA — optional. If true, save the card token
+    // after success; the bound card becomes available in /account/cards.
+    bool save_payment_method = 6;
+}
+
+message BindCardRequest {
+    string user_id = 1;
+    string return_url = 2;
+}
+
+message GetPaymentIntentRequest {
+    string intent_id = 1;
+    string user_id = 2; // ownership check
+}
+
+message PaymentIntentStatus {
+    string id = 1;
+    string user_id = 2;
+    string purpose = 3;          // TOPUP | PREMIUM
+    string status = 4;           // PENDING | COMPLETED | FAILED | CANCELED
+    string amount = 5;
+    string currency = 6;
+    string purchase_id = 7;      // set when purpose=PREMIUM (else empty)
+    string created_at = 8;
+    string updated_at = 9;
+}
+
+message CheckoutResponse {
+    string purchase_id = 1;
+    string payment_id = 2;
+    string confirmation_url = 3; // empty when paid from balance (instant)
+    string status = 4;           // PENDING (redirect) | COMPLETED (balance)
+    string intent_id = 5;        // poll via GetPaymentIntent for TOPUP / bind-card flows
+}
+
+message GetMyPurchasesRequest { string user_id = 1; int32 page = 2; int32 limit = 3; }
+message PurchasesListResponse { repeated Purchase items = 1; int32 total = 2; int32 page = 3; int32 limit = 4; }
+message GetPurchaseRequest { string id = 1; string user_id = 2; }
+message RefundPurchaseRequest { string purchase_id = 1; string actor_user_id = 2; bool is_admin = 3; string reason = 4; }
+
+// ---------------------------------------------------------------------------
+// Wallet & statement
+// ---------------------------------------------------------------------------
+message GetWalletRequest { string user_id = 1; }
+message WalletResponse {
+    string spending = 1;
+    string pending = 2;
+    string payout = 3;
+    string spendable = 4;   // spending + payout
+    string withdrawable = 5; // payout
+    string currency = 6;
+    int32 lifetime_sales = 7;
+    string current_commission_percent = 8;
+}
+
+message ListTransactionsRequest {
+    string user_id = 1;
+    // Legacy low-level filter (one of LedgerTxType). Kept for backward
+    // compatibility — admin tooling still uses it directly.
+    string type = 2;
+    int32 page = 3;
+    int32 limit = 4;
+    // ↓ added for the wallet statement page (Round 3)
+    // UI-semantic filter mapped onto displayKind:
+    //   ALL | SALES | INCOME | OUTCOME | REFUND | WITHDRAWAL | PREMIUM
+    // SALES = the seller's earnings on this account (USER_PENDING credits from
+    // PURCHASE transactions); these stay separate from INCOME (TOPUP).
+    string flow = 5;
+    // Period selection. `month` is the convenience form (YYYY-MM) used by the
+    // month dropdown; from/to override it for an arbitrary range.
+    string month = 6;
+    string from = 7;
+    string to = 8;
+    // Filter wallet to purchases/refunds of a specific Product category. Has
+    // no effect on TOPUP/WITHDRAWAL/PREMIUM/ADJUSTMENT entries (they have no
+    // product).
+    string product_category_id = 9;
+    // sort_by ∈ { date | amount | type }. Default: date.
+    string sort_by = 10;
+    // order ∈ { asc | desc }. Default: desc.
+    string order = 11;
+}
+message StatementEntry {
+    string id = 1;
+    string tx_id = 2;
+    string type = 3;          // raw tx type (TOPUP|PURCHASE|...)
+    string account_kind = 4;
+    string direction = 5;     // DEBIT | CREDIT
+    string amount = 6;
+    string description = 7;
+    string created_at = 8;
+    // ↓ added for the wallet statement page (Round 3)
+    // UI-friendly classification computed server-side:
+    //   TOPUP | PURCHASE | SALE | REFUND | PREMIUM | WITHDRAWAL | ADJUSTMENT
+    // SALE is the seller's view of someone else's PURCHASE (CREDIT to their
+    // USER_PENDING) — distinct from PURCHASE which is the buyer's DEBIT.
+    // PREMIUM is split out of PURCHASE/REFUND so the UI can show
+    // "Продление Premium" / refund-of-premium in their own filter bucket.
+    // SALE_CLEAR transactions are excluded from the wallet view — the maturity
+    // event is surfaced via sale_status on the original SALE row instead.
+    string display_kind = 9;
+    string balance_after = 10;       // affected-account running balance, Decimal-as-string
+    string product_id = 11;          // empty for non-product entries
+    string product_name = 12;
+    string product_category = 13;    // "Assets" | "Project File" | "Templates"
+    string product_preview = 14;     // optional thumbnail URL for richer rows
+    // Sale lifecycle. Populated only when display_kind=SALE.
+    //   PENDING — held in USER_PENDING, not yet withdrawable.
+    //   MATURED — SALE_CLEAR has fired; money is in USER_PAYOUT.
+    string sale_status = 15;
+    // ISO 8601 when the sale becomes withdrawable (sale_completed_at +
+    // GRACE_DAYS). Empty for non-sale rows.
+    string matures_at = 16;
+}
+message TransactionsListResponse { repeated StatementEntry items = 1; int32 total = 2; int32 page = 3; int32 limit = 4; }
+
+message GetTransactionMonthsRequest { string user_id = 1; }
+message GetTransactionMonthsResponse {
+    // Newest first. "YYYY-MM" strings; the dropdown renders them
+    // localized client-side.
+    repeated string months = 1;
+}
+
+// ---------------------------------------------------------------------------
+// Withdrawals
+// ---------------------------------------------------------------------------
+message Withdrawal {
+    string id = 1;
+    string seller_id = 2;
+    string amount = 3;
+    string status = 4;     // PENDING | PROCESSING | COMPLETED | REJECTED
+    string method = 5;
+    string details = 6;
+    string comment = 7;
+    string processed_by = 8;
+    string processed_at = 9;
+    string created_at = 10;
+}
+message RequestWithdrawalRequest { string seller_id = 1; string amount = 2; string method = 3; string details = 4; }
+message ListWithdrawalsRequest { string seller_id = 1; string status = 2; int32 page = 3; int32 limit = 4; }
+message WithdrawalsListResponse { repeated Withdrawal items = 1; int32 total = 2; int32 page = 3; int32 limit = 4; }
+message ProcessWithdrawalRequest { string withdrawal_id = 1; string admin_id = 2; string action = 3; string comment = 4; }
+
+// ---------------------------------------------------------------------------
+// Webhook
+// ---------------------------------------------------------------------------
+message PaymentEventRequest { string event = 1; string payment_id = 2; }
+
+message ProviderCallbackRequest {
+    string provider = 1; // yookassa | heleket | …
+    string raw_body = 2; // exact raw JSON body as received (signature input)
+}
+
+// ---------------------------------------------------------------------------
+// FX rates / payment methods
+// ---------------------------------------------------------------------------
+message GetRatesRequest {}
+
+message FxRate {
+    string currency = 1; // USD | EUR
+    string rate = 2;     // RUB per 1 unit, Decimal as string
+}
+
+message GetRatesResponse {
+    string base = 1;  // always RUB
+    string as_of = 2; // YYYY-MM-DD the rates are for
+    repeated FxRate rates = 3;
+}
+
+message GetPaymentMethodsRequest {}
+
+message PaymentMethodInfo {
+    string method = 1;             // YOOKASSA | SAVED_CARD | CRYPTO | BALANCE
+    string provider = 2;           // yookassa | heleket | '' (BALANCE)
+    repeated string currencies = 3;
+}
+
+message GetPaymentMethodsResponse {
+    repeated PaymentMethodInfo methods = 1;
+}
+
+// ---------------------------------------------------------------------------
+// Admin
+// ---------------------------------------------------------------------------
+message AdminOverviewRequest { string from = 1; string to = 2; }
+message AdminOverviewResponse {
+    string revenue = 1;          // platform commission earned (period)
+    string gmv = 2;              // gross merchandise value (period)
+    string liabilities = 3;      // Σ all users' (pending+payout+spending) — what we owe
+    string psp_clearing = 4;     // money in transit at PSP
+    string payouts_payable = 5;  // reserved for approved withdrawals
+    string refunds_total = 6;
+    string topups_total = 7;
+    string withdrawals_total = 8;
+    int32 sales_count = 9;
+    string currency = 10;
+}
+
+message AdminListTransactionsRequest {
+    string type = 1;
+    string user_id = 2;
+    string account_kind = 3;
+    string from = 4;
+    string to = 5;
+    int32 page = 6;
+    int32 limit = 7;
+}
+message AdminEntry { string account_id = 1; string account_kind = 2; string owner_id = 3; string direction = 4; string amount = 5; }
+message AdminLedgerTx {
+    string id = 1;
+    string type = 2;
+    string status = 3;
+    string ref_type = 4;
+    string ref_id = 5;
+    string description = 6;
+    string created_by = 7;
+    string created_at = 8;
+    repeated AdminEntry entries = 9;
+}
+message AdminTransactionsListResponse { repeated AdminLedgerTx items = 1; int32 total = 2; int32 page = 3; int32 limit = 4; }
+
+message GetUserFinanceRequest { string user_id = 1; }
+message AccountBalance { string kind = 1; string balance = 2; string currency = 3; }
+message UserFinanceResponse {
+    WalletResponse wallet = 1;
+    repeated AccountBalance accounts = 2;
+    repeated StatementEntry recent = 3;
+}
+
+message CreateAdjustmentRequest {
+    string admin_id = 1;
+    string user_id = 2;
+    string account_kind = 3; // USER_SPENDING | USER_PAYOUT | USER_PENDING
+    string direction = 4;    // CREDIT (give) | DEBIT (take)
+    string amount = 5;
+    string reason = 6;
+}
+
+message SalesAnalyticsRequest { string from = 1; string to = 2; string granularity = 3; } // day|week|month
+message SalesPoint { string date = 1; int32 sales_count = 2; string gmv = 3; string revenue = 4; }
+message SellerStat { string seller_id = 1; string username = 2; int32 sales = 3; string gmv = 4; }
+message SalesAnalyticsResponse {
+    repeated SalesPoint points = 1;
+    repeated SellerStat top_sellers = 2;
+    string refund_rate = 3; // % refunded purchases
+}
+
+// ---------------------------------------------------------------------------
+// Premium
+// ---------------------------------------------------------------------------
+message GetPremiumPlansRequest {}
+
+// One plan per (period). Prices are computed server-side from BASE_PRICE × months
+// × (1 − discount); kept here as canonical strings so the gateway has no math.
+message PremiumPlan {
+    string period = 1;          // MONTH_1 | MONTH_3 | MONTH_6 | MONTH_12
+    int32 months = 2;
+    string price = 3;           // total to charge, Decimal-as-string
+    string monthly_price = 4;   // for UI "≈ X ₽/month"
+    string discount_percent = 5;
+    string currency = 6;
+}
+
+message PremiumPlansResponse {
+    repeated PremiumPlan plans = 1;
+    string base_monthly_price = 2;
+}
+
+message PurchasePremiumRequest {
+    string user_id = 1;
+    string period = 2;           // MONTH_1 | MONTH_3 | MONTH_6 | MONTH_12
+    string payment_method = 3;   // BALANCE | YOOKASSA | SAVED_CARD (empty = smart default)
+    string return_url = 4;       // YooKassa only
+    // Save the YooKassa payment_method for future auto-renewals. Ignored for
+    // BALANCE. Kept for backwards compatibility; auto_renew=true implies save.
+    bool save_payment_method = 5;
+    bool auto_renew = 6;         // default false; requires off-session-capable method
+    string saved_card_id = 7;    // optional for SAVED_CARD; empty = default card
+}
+
+message PurchasePremiumResponse {
+    string payment_id = 1;       // PremiumPayment.id
+    string confirmation_url = 2; // empty for BALANCE (instant) or YooKassa-issued
+    string status = 3;           // PENDING (redirect) | COMPLETED (balance)
+}
+
+message RunPremiumRenewalsRequest {
+    int32 max_batch = 1;         // safety cap; default 100
+}
+
+message RunPremiumRenewalsResponse {
+    int32 attempted = 1;
+    int32 succeeded = 2;
+    int32 failed = 3;
+}
+
+message SetPremiumPaymentMethodRequest {
+    string user_id = 1;
+    string method = 2;           // BALANCE | YOOKASSA | SAVED_CARD
+    string saved_card_id = 3;    // optional for SAVED_CARD; empty = default card
+}
+
+message PremiumPaymentMethodResponse {
+    string method = 1;           // BALANCE | YOOKASSA | SAVED_CARD
+    string saved_card_id = 2;    // empty unless SAVED_CARD
+    bool auto_renew = 3;
+}
+
+message PremiumPaymentRow {
+    string id = 1;
+    string user_id = 2;
+    string amount = 3;
+    string period = 4;          // MONTH_1 | MONTH_3 | MONTH_6 | MONTH_12
+    string method = 5;          // BALANCE | YOOKASSA
+    string status = 6;          // PENDING | COMPLETED | FAILED | REFUNDED
+    bool is_renewal = 7;
+    string created_at = 8;
+    string completed_at = 9;
+    string refunded_at = 10;
+    string refunded_amount = 11;
+    // Convenience: true if this payment is currently inside the 7-day refund
+    // window AND status == COMPLETED AND not already refunded.
+    bool refundable = 12;
+}
+
+message RefundPremiumRequest {
+    string user_id = 1;
+    string payment_id = 2;
+    string reason = 3;          // optional
+}
+
+message RefundPremiumResponse {
+    PremiumPaymentRow payment = 1;
+    string new_expires_at = 2;  // ISO 8601 after rollback
+    bool subscription_revoked = 3; // true when rollback put expiresAt <= now
+}
+
+message GetMyPremiumPaymentsRequest {
+    string user_id = 1;
+    int32 page = 2;
+    int32 limit = 3;
+}
+
+message GetPremiumPaymentRequest {
+    string user_id = 1;
+    string payment_id = 2;
+}
+
+message PremiumPaymentsListResponse {
+    repeated PremiumPaymentRow items = 1;
+    int32 total = 2;
+    int32 page = 3;
+    int32 limit = 4;
+}
+
+// ---------------------------------------------------------------------------
+// Saved cards (YooKassa payment_method tokens; we never see PAN)
+// ---------------------------------------------------------------------------
+message SavedCard {
+    string id = 1;
+    string brand = 2;       // "MIR" | "VISA" | "MASTERCARD" | ""
+    string last4 = 3;       // "0000" etc, display-only
+    int32 exp_month = 4;
+    int32 exp_year = 5;
+    bool is_default = 6;
+    string nickname = 7;    // user-set label
+    string created_at = 8;
+}
+
+message ListSavedCardsRequest { string user_id = 1; }
+message ListSavedCardsResponse { repeated SavedCard items = 1; }
+
+message DeleteSavedCardRequest { string user_id = 1; string id = 2; }
+
+message SetDefaultSavedCardRequest { string user_id = 1; string id = 2; }
+
+message UpdateSavedCardRequest {
+    string user_id = 1;
+    string id = 2;
+    string nickname = 3; // empty = clear
+}
+
+// ---------------------------------------------------------------------------
+// Payout details (persistent default; per-withdrawal override still allowed)
+// ---------------------------------------------------------------------------
+message UpdatePayoutDetailsRequest {
+    string user_id = 1;
+    string method = 2;  // "card" | "sbp" | "bank" | "" (clear)
+    string details = 3; // JSON string — payments-service treats opaquely
+}
+
+message UpdatePayoutDetailsResponse {
+    string method = 1;
+    string details = 2;
+}
+
+message GetPayoutDetailsRequest { string user_id = 1; }