feat(payments): Telegram Stars payment rail
CI / changes (pull_request) Successful in 2s
CI / unit (pull_request) Successful in 22s
CI / integration (pull_request) Successful in 20s
CI / ui (pull_request) Successful in 1m10s
CI / conformance (pull_request) Successful in 10s
CI / gate (pull_request) Successful in 0s
CI / deploy (pull_request) Successful in 1m57s
CI / changes (pull_request) Successful in 2s
CI / unit (pull_request) Successful in 22s
CI / integration (pull_request) Successful in 20s
CI / ui (pull_request) Successful in 1m10s
CI / conformance (pull_request) Successful in 10s
CI / gate (pull_request) Successful in 0s
CI / deploy (pull_request) Successful in 1m57s
Accept real money via Telegram Stars (XTR) — the third intake rail alongside Robokassa (direct) and VK Votes. Only the bot reaches Telegram, so the rail funnels through the reverse mTLS bot-link: - the gateway mints the invoice on a CreateInvoice command (the bot calls createInvoiceLink, XTR; the link goes to WebApp.openInvoice); - the bot gates each pre_checkout_query via a ValidatePreCheckout unary (the order must exist, be still creditable and not already paid — the reusable-invoice double-pay guard; the decline reason is localised to the order account's language); - a completed successful_payment is queued in a durable pure-Go SQLite outbox and forwarded via a ForwardPayment unary, credited once (idempotent on telegram_payment_charge_id, honours an expired order), re-driven on restart and every 30s. The rail is wired by TELEGRAM_STARS_OUTBOX_DIR (default /data) but stays inert until a chip pack carries an XTR price, so seeding a Stars price in the admin is the go-live. Tests: backend integration (order->forward->credit once, duplicate, pre_checkout gate) + bot outbox unit (idempotent, restart re-drive) + executor createInvoice. Docs: PAYMENTS(+ru) §9, ARCHITECTURE, the platform/telegram README, PLAN.
This commit is contained in:
@@ -2,6 +2,7 @@ package payments
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
|
||||
"github.com/google/uuid"
|
||||
@@ -80,6 +81,49 @@ func (s *Service) Fund(ctx context.Context, orderID uuid.UUID, provider, provide
|
||||
return s.store.fund(ctx, orderID, provider, providerPaymentID, paid, s.clock())
|
||||
}
|
||||
|
||||
// Pre-checkout decline reason codes. They are language-neutral: the transport layer localises them
|
||||
// to the order account's preferred language before showing the payer (the reason is displayed in the
|
||||
// Telegram payment sheet).
|
||||
const (
|
||||
// PreCheckoutGone means no order matches — an unknown or stale invoice payload.
|
||||
PreCheckoutGone = "order_gone"
|
||||
// PreCheckoutAlreadyPaid means the order is already paid (a reusable invoice link paid twice).
|
||||
PreCheckoutAlreadyPaid = "already_paid"
|
||||
// PreCheckoutPriceChanged means the amount or currency no longer matches the order.
|
||||
PreCheckoutPriceChanged = "price_changed"
|
||||
)
|
||||
|
||||
// PreCheckoutOutcome is the pre-charge validation of a Telegram Stars order. OK approves the charge;
|
||||
// otherwise Reason is a decline reason code the transport localises. AccountID is the order's account
|
||||
// (for localising the reason to its preferred language); it is the zero UUID when the order is unknown.
|
||||
type PreCheckoutOutcome struct {
|
||||
OK bool
|
||||
Reason string
|
||||
AccountID uuid.UUID
|
||||
}
|
||||
|
||||
// ValidatePreCheckout answers whether a Stars pre_checkout_query for orderID paying amount may be
|
||||
// approved, before any star is charged. It approves an order that exists, is not already paid (a
|
||||
// reusable invoice link paid a second time is refused here) and whose expected amount and currency
|
||||
// match the invoice. A pending or honoured-expired order is approved — a late credit is honoured
|
||||
// (§9/D23). A missing order or a mismatch is a clean decline with a reason code, not an error.
|
||||
func (s *Service) ValidatePreCheckout(ctx context.Context, orderID uuid.UUID, amount Money) (PreCheckoutOutcome, error) {
|
||||
ord, err := s.store.orderByID(ctx, orderID)
|
||||
if errors.Is(err, ErrOrderNotFound) {
|
||||
return PreCheckoutOutcome{OK: false, Reason: PreCheckoutGone}, nil
|
||||
}
|
||||
if err != nil {
|
||||
return PreCheckoutOutcome{}, err
|
||||
}
|
||||
if ord.status == "paid" {
|
||||
return PreCheckoutOutcome{OK: false, Reason: PreCheckoutAlreadyPaid, AccountID: ord.accountID}, nil
|
||||
}
|
||||
if amount.Currency() != Currency(ord.currency) || amount.Minor() != ord.expectedAmount {
|
||||
return PreCheckoutOutcome{OK: false, Reason: PreCheckoutPriceChanged, AccountID: ord.accountID}, nil
|
||||
}
|
||||
return PreCheckoutOutcome{OK: true, AccountID: ord.accountID}, nil
|
||||
}
|
||||
|
||||
// ExpireOrders marks pending orders older than the configured lifetime as expired, returning how
|
||||
// many were swept. It backs the periodic pending reaper; expiry is cosmetic (a late valid callback
|
||||
// still credits — see Fund).
|
||||
|
||||
Reference in New Issue
Block a user