feat(payments): payment-event dispatcher + the provider-return UX

Deliver payment_events to connected clients as an in-app wallet-refresh push: a
background dispatcher drains undispatched events and publishes a KindNotification
"payment" signal, marking each delivered; the client bumps a wallet-refresh
counter the open Wallet screen watches, re-fetching in place. A return-focus
refetch is the fallback. The Robokassa Success/Fail return now serves a
self-closing page (the payment opens in a separate window) so the customer drops
back into the live app instead of a cold start. Integration test for the event
drain/mark queue.

backend/cmd/backend/main.go

@@ -320,6 +320,9 @@ func run(ctx context.Context, cfg config.Config, logger *zap.Logger) error {
 	// Sweep expired pending payment orders on a cadence (cosmetic hygiene; a late valid callback
 	// still credits). Runs until ctx is cancelled.
 	go runOrderReaper(ctx, paymentsSvc, logger)
+	// Deliver pending payment_events to connected clients as an in-app wallet-refresh push (the
+	// credit already landed in the ledger; a return-focus poll is the client-side fallback).
+	go runPaymentDispatcher(ctx, paymentsSvc, hub, logger)
 
 	errc := make(chan error, 2)
 	go func() { errc <- pushSrv.Run(ctx) }()
@@ -350,6 +353,32 @@ func runOrderReaper(ctx context.Context, p *payments.Service, log *zap.Logger) {
 	}
 }
 
+// runPaymentDispatcher delivers pending payment_events to connected clients as a wallet-refresh
+// signal (KindNotification / "payment"), marking each delivered, until ctx is cancelled. The credit
+// already committed to the ledger; this is only the in-app push so an open wallet updates in place.
+func runPaymentDispatcher(ctx context.Context, p *payments.Service, pub notify.Publisher, log *zap.Logger) {
+	t := time.NewTicker(3 * time.Second)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+			evs, err := p.UndispatchedEvents(ctx, 50)
+			if err != nil {
+				log.Warn("payment dispatcher: read failed", zap.Error(err))
+				continue
+			}
+			for _, e := range evs {
+				pub.Publish(notify.Notification(e.AccountID, notify.NotifyPayment))
+				if err := p.MarkEventDispatched(ctx, e.EventID); err != nil {
+					log.Warn("payment dispatcher: mark failed", zap.String("event", e.EventID.String()), zap.Error(err))
+				}
+			}
+		}
+	}
+}
+
 // newMailer builds the confirm-code mailer: an SMTP relay when a host is
 // configured, otherwise the development log mailer (the code is logged, not sent).
 func newMailer(cfg account.SMTPConfig, logger *zap.Logger) account.Mailer {

backend/internal/inttest/payments_intake_test.go

@@ -101,6 +101,45 @@ func TestPaymentsFundAmountMismatch(t *testing.T) {
 	}
 }
 
+// TestPaymentsEventDispatchDrain verifies the payment_events dispatcher queue: a recorded event is
+// returned as undispatched until marked, then drops out (so the dispatcher delivers it once).
+func TestPaymentsEventDispatchDrain(t *testing.T) {
+	ctx := context.Background()
+	svc := newPaymentsService()
+	acc := uuid.New()
+	if err := svc.RecordPaymentEvent(ctx, acc, nil, "succeeded", []byte(`{"chips":10,"source":"direct"}`)); err != nil {
+		t.Fatalf("record event: %v", err)
+	}
+
+	// testDB is shared, so filter the queue to our account.
+	find := func() *payments.PaymentEvent {
+		evs, err := svc.UndispatchedEvents(ctx, 100)
+		if err != nil {
+			t.Fatalf("undispatched: %v", err)
+		}
+		for i := range evs {
+			if evs[i].AccountID == acc {
+				return &evs[i]
+			}
+		}
+		return nil
+	}
+
+	mine := find()
+	if mine == nil {
+		t.Fatal("recorded event not in the undispatched queue")
+	}
+	if mine.Type != "succeeded" {
+		t.Errorf("event type = %s, want succeeded", mine.Type)
+	}
+	if err := svc.MarkEventDispatched(ctx, mine.EventID); err != nil {
+		t.Fatalf("mark dispatched: %v", err)
+	}
+	if find() != nil {
+		t.Error("event still undispatched after MarkEventDispatched")
+	}
+}
+
 // TestPaymentsExpiredOrderStillCredits verifies an expired pending order is still honoured by a
 // later valid callback (§9/D23: expiry is cosmetic, the money is real).
 func TestPaymentsExpiredOrderStillCredits(t *testing.T) {

backend/internal/notify/notify.go

@@ -73,6 +73,10 @@ const (
 	// (e.g. an email was confirmed via the one-tap deeplink opened in another browser),
 	// so it re-fetches profile.get. It carries no payload. In-app only.
 	NotifyProfile = "profile"
+	// NotifyPayment tells the client that the viewer's wallet changed from a payment-intake event
+	// (a credit or a refund), so it re-fetches the wallet in place. It carries no payload. In-app
+	// only; the payment_events dispatcher emits it after the crediting transaction commits.
+	NotifyPayment = "payment"
 	// NotifyUserBlocked confirms to the blocker that a per-user block took effect,
 	// carrying the blocked account, so every one of the blocker's sessions updates the
 	// in-game block/add-friend controls and the struck name in place. It is delivered

backend/internal/payments/service_intake.go

@@ -77,3 +77,14 @@ func (s *Service) ExpireOrders(ctx context.Context) (int, error) {
 func (s *Service) RecordPaymentEvent(ctx context.Context, accountID uuid.UUID, orderID *uuid.UUID, eventType string, payload []byte) error {
 	return s.store.insertPaymentEvent(ctx, accountID, orderID, eventType, payload, s.clock())
 }
+
+// UndispatchedEvents returns up to limit payment events awaiting delivery. The dispatcher drains
+// them and marks each delivered via MarkEventDispatched.
+func (s *Service) UndispatchedEvents(ctx context.Context, limit int) ([]PaymentEvent, error) {
+	return s.store.undispatchedEvents(ctx, limit)
+}
+
+// MarkEventDispatched stamps a payment event as delivered so it is not re-sent.
+func (s *Service) MarkEventDispatched(ctx context.Context, eventID uuid.UUID) error {
+	return s.store.markEventDispatched(ctx, eventID, s.clock())
+}

backend/internal/payments/store_intake.go

@@ -292,6 +292,42 @@ func (s *Store) insertPaymentEvent(ctx context.Context, accountID uuid.UUID, ord
 	return nil
 }
 
+// PaymentEvent is an undispatched lifecycle event the dispatcher delivers to an account.
+type PaymentEvent struct {
+	EventID   uuid.UUID
+	AccountID uuid.UUID
+	Type      string
+}
+
+// undispatchedEvents reads up to limit payment events not yet delivered, oldest first.
+func (s *Store) undispatchedEvents(ctx context.Context, limit int) ([]PaymentEvent, error) {
+	rows, err := s.db.QueryContext(ctx,
+		`SELECT event_id, account_id, type FROM payments.payment_events
+		 WHERE dispatched_at IS NULL ORDER BY created_at LIMIT $1`, limit)
+	if err != nil {
+		return nil, fmt.Errorf("payments: read undispatched events: %w", err)
+	}
+	defer rows.Close()
+	var out []PaymentEvent
+	for rows.Next() {
+		var e PaymentEvent
+		if err := rows.Scan(&e.EventID, &e.AccountID, &e.Type); err != nil {
+			return nil, fmt.Errorf("payments: scan event: %w", err)
+		}
+		out = append(out, e)
+	}
+	return out, rows.Err()
+}
+
+// markEventDispatched stamps an event as delivered so it is not re-sent.
+func (s *Store) markEventDispatched(ctx context.Context, eventID uuid.UUID, now time.Time) error {
+	if _, err := s.db.ExecContext(ctx,
+		`UPDATE payments.payment_events SET dispatched_at = $2 WHERE event_id = $1`, eventID, now); err != nil {
+		return fmt.Errorf("payments: mark event dispatched: %w", err)
+	}
+	return nil
+}
+
 // orderTTL reads the configured pending-order lifetime in whole seconds.
 func (s *Store) orderTTL(ctx context.Context) (int, error) {
 	var cfg model.Config