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

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:
Ilia Denisov
2026-07-09 21:35:29 +02:00
parent 5612bb624d
commit 6e03ce0131
32 changed files with 1830 additions and 94 deletions
+31 -7
View File
@@ -27,6 +27,10 @@ type Sender interface {
// chat, but only when they are currently in it; it reports whether a restriction
// was applied.
ApplyChatGate(ctx context.Context, userID int64, allow bool) (bool, error)
// CreateInvoiceLink mints a Telegram Stars invoice link (XTR) for amountStars, tagged
// with payload (the order id, echoed back in pre_checkout and successful_payment), and
// returns the link.
CreateInvoiceLink(ctx context.Context, title, description, payload string, amountStars int64) (string, error)
}
// Executor turns a bot-link Command into a Bot API send. The delivered flag mirrors
@@ -48,22 +52,42 @@ func NewExecutor(sender Sender, channelID int64, log *zap.Logger) *Executor {
return &Executor{sender: sender, channelID: channelID, log: log}
}
// Handle dispatches one command to the matching Bot API send.
func (e *Executor) Handle(ctx context.Context, cmd *botlinkv1.Command) (bool, error) {
// Handle dispatches one command to the matching Bot API call. It returns whether the command was
// delivered, an optional result string (the created invoice link for a create_invoice command; empty
// otherwise), and an error for an unexpected or malformed failure.
func (e *Executor) Handle(ctx context.Context, cmd *botlinkv1.Command) (bool, string, error) {
switch p := cmd.GetPayload().(type) {
case *botlinkv1.Command_Notify:
return e.notify(ctx, p.Notify)
d, err := e.notify(ctx, p.Notify)
return d, "", err
case *botlinkv1.Command_SendToUser:
return e.sendToUser(ctx, p.SendToUser)
d, err := e.sendToUser(ctx, p.SendToUser)
return d, "", err
case *botlinkv1.Command_SendToChannel:
return e.sendToChannel(ctx, p.SendToChannel)
d, err := e.sendToChannel(ctx, p.SendToChannel)
return d, "", err
case *botlinkv1.Command_ChatGate:
return e.chatGate(ctx, p.ChatGate)
d, err := e.chatGate(ctx, p.ChatGate)
return d, "", err
case *botlinkv1.Command_CreateInvoice:
return e.createInvoice(ctx, p.CreateInvoice)
default:
return false, fmt.Errorf("botlink: empty command")
return false, "", fmt.Errorf("botlink: empty command")
}
}
// createInvoice mints a Telegram Stars invoice link for the order and returns it in the Ack result.
// A Bot API failure is a hard error carried back in the Ack, so the gateway's synchronous mint fails
// (rather than returning an empty link).
func (e *Executor) createInvoice(ctx context.Context, req *botlinkv1.CreateInvoiceCommand) (bool, string, error) {
link, err := e.sender.CreateInvoiceLink(ctx, req.GetTitle(), req.GetDescription(), req.GetPayload(), req.GetAmount())
if err != nil {
e.log.Warn("create invoice link failed", zap.String("order", req.GetPayload()), zap.Error(err))
return false, "", err
}
return true, link, nil
}
// chatGate applies a chat-gate command: it parses the target Telegram user id and
// sets their write access in the moderated chat (a no-op when they are not in it). A
// Bot API failure is logged and reported as not-delivered, not a hard error.