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:
@@ -0,0 +1,104 @@
|
||||
// Package outbox is the Telegram Stars payment outbox: a small SQLite store on the bot host's
|
||||
// writable volume that durably records each completed Stars payment the moment Telegram delivers it,
|
||||
// so a gateway or backend outage cannot lose it. The bot forwards pending rows to the gateway and
|
||||
// marks them delivered; rows still undelivered are re-driven on restart. It is pure-Go SQLite
|
||||
// (modernc.org/sqlite, no CGO) so it runs on the distroless image.
|
||||
package outbox
|
||||
|
||||
import (
|
||||
"context"
|
||||
"database/sql"
|
||||
"fmt"
|
||||
"time"
|
||||
|
||||
_ "modernc.org/sqlite"
|
||||
)
|
||||
|
||||
// Record is one completed Stars payment awaiting delivery to the gateway.
|
||||
type Record struct {
|
||||
// ChargeID is the telegram_payment_charge_id — the primary key here and the credit idempotency
|
||||
// key at the backend, so a re-delivered or retried payment is never credited twice.
|
||||
ChargeID string
|
||||
// OrderID is the invoice payload (our order id) the payment settles.
|
||||
OrderID string
|
||||
// Amount is the stars paid (the XTR minor unit is the whole star).
|
||||
Amount int64
|
||||
// UserID is the payer's Telegram user id.
|
||||
UserID int64
|
||||
}
|
||||
|
||||
// Store is the SQLite-backed payment outbox.
|
||||
type Store struct {
|
||||
db *sql.DB
|
||||
}
|
||||
|
||||
// Open opens (creating if absent) the outbox database at path and ensures its schema. The parent
|
||||
// directory must exist and be writable by the container user.
|
||||
func Open(path string) (*Store, error) {
|
||||
db, err := sql.Open("sqlite", path)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("outbox: open %s: %w", path, err)
|
||||
}
|
||||
// A single connection serialises writes and sidesteps SQLite's "database is locked" under the
|
||||
// bot's low, bursty payment volume.
|
||||
db.SetMaxOpenConns(1)
|
||||
if _, err := db.Exec(`CREATE TABLE IF NOT EXISTS stars_payments (
|
||||
charge_id TEXT PRIMARY KEY,
|
||||
order_id TEXT NOT NULL,
|
||||
amount INTEGER NOT NULL,
|
||||
user_id INTEGER NOT NULL,
|
||||
created_at INTEGER NOT NULL,
|
||||
forwarded INTEGER NOT NULL DEFAULT 0
|
||||
)`); err != nil {
|
||||
_ = db.Close()
|
||||
return nil, fmt.Errorf("outbox: init schema: %w", err)
|
||||
}
|
||||
return &Store{db: db}, nil
|
||||
}
|
||||
|
||||
// Close closes the database.
|
||||
func (s *Store) Close() error { return s.db.Close() }
|
||||
|
||||
// Add records a completed payment. It is idempotent on the charge id: a payment Telegram re-delivers
|
||||
// (or one already recorded and forwarded) is ignored, so it is never forwarded — and credited —
|
||||
// twice.
|
||||
func (s *Store) Add(ctx context.Context, r Record) error {
|
||||
_, err := s.db.ExecContext(ctx,
|
||||
`INSERT INTO stars_payments (charge_id, order_id, amount, user_id, created_at, forwarded)
|
||||
VALUES (?, ?, ?, ?, ?, 0)
|
||||
ON CONFLICT(charge_id) DO NOTHING`,
|
||||
r.ChargeID, r.OrderID, r.Amount, r.UserID, time.Now().Unix())
|
||||
if err != nil {
|
||||
return fmt.Errorf("outbox: add %s: %w", r.ChargeID, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// Pending returns up to limit payments not yet forwarded, oldest first.
|
||||
func (s *Store) Pending(ctx context.Context, limit int) ([]Record, error) {
|
||||
rows, err := s.db.QueryContext(ctx,
|
||||
`SELECT charge_id, order_id, amount, user_id FROM stars_payments
|
||||
WHERE forwarded = 0 ORDER BY created_at LIMIT ?`, limit)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("outbox: read pending: %w", err)
|
||||
}
|
||||
defer rows.Close()
|
||||
var out []Record
|
||||
for rows.Next() {
|
||||
var r Record
|
||||
if err := rows.Scan(&r.ChargeID, &r.OrderID, &r.Amount, &r.UserID); err != nil {
|
||||
return nil, fmt.Errorf("outbox: scan: %w", err)
|
||||
}
|
||||
out = append(out, r)
|
||||
}
|
||||
return out, rows.Err()
|
||||
}
|
||||
|
||||
// MarkForwarded flags a payment as delivered so it is not forwarded again.
|
||||
func (s *Store) MarkForwarded(ctx context.Context, chargeID string) error {
|
||||
if _, err := s.db.ExecContext(ctx,
|
||||
`UPDATE stars_payments SET forwarded = 1 WHERE charge_id = ?`, chargeID); err != nil {
|
||||
return fmt.Errorf("outbox: mark forwarded %s: %w", chargeID, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
Reference in New Issue
Block a user