Phase 1 (commit 2a96766a) opened the pending_payment status: a paid-plan
subscribe path creates a UserSubscription row in pending_payment +
subscription_invoices row carrying the Hyperswitch payment_id, then hands
the client_secret back to the SPA. Phase 2 lands the webhook side: the
PSP-driven state transition that closes the loop.
State machine:
- pending_payment + status=succeeded → invoice paid (paid_at=now), sub active
- pending_payment + status=failed → invoice failed, sub expired
- already terminal → idempotent no-op (paid_at NOT bumped)
- payment_id not in subscription_invoices → marketplace.ErrNotASubscription
(caller falls through to the order webhook flow)
The processor only flips a subscription out of pending_payment. Rows that
have already transitioned (concurrent flow, manual admin action, plan
upgrade) are left alone — the invoice still gets the terminal status
update so the audit trail stays consistent.
New surface:
- hyperswitch.SubscriptionWebhookProcessor — the actual handler. Reads
subscription_invoices by hyperswitch_payment_id, looks up the parent
user_subscriptions row, applies the transition in a single tx.
- hyperswitch.IsSubscriptionEventType — exported helper for callers
that want to skip the DB hit on clearly non-subscription events.
- marketplace.SubscriptionWebhookHandler (interface) +
marketplace.ErrNotASubscription (sentinel) — keeps marketplace from
importing the hyperswitch package while still allowing
ProcessPaymentWebhook to dispatch typed.
- marketplace.WithSubscriptionWebhookHandler (option) — wired by
routes_webhooks.getMarketplaceService so the prod webhook handler
routes subscription events instead of swallowing them as "order not
found".
Dispatcher in ProcessPaymentWebhook: try subscription first, fall through
to the order flow on ErrNotASubscription. Order events are unchanged.
Tests (4, sqlite in-memory, all green):
- Succeeded: pending_payment → active+paid, paid_at set
- Failed: pending_payment → expired+failed
- Idempotent replay: second succeeded webhook is a no-op, paid_at NOT
re-stamped (locks down Hyperswitch's at-least-once delivery contract)
- Unknown payment_id: returns marketplace.ErrNotASubscription so the
dispatcher falls through to ProcessPaymentWebhook's order flow
Removes the v1.0.6.2 "active row without PSP linkage" fantôme pattern
that hasEffectivePayment had to filter retroactively — the Phase 1 +
Phase 2 pair is now the canonical paid-plan creation path.
E2E + recovery endpoint (POST /api/v1/subscriptions/complete/:id) +
distribution gate land in Phase 3 (Day 3 of ROADMAP_V1.0_LAUNCH.md).
SKIP_TESTS=1 rationale: this commit is backend-only (Go); the husky
pre-commit hook only runs frontend typecheck/lint/vitest. Backend tests
verified manually:
$ go test -short -count=1 ./internal/services/hyperswitch/... ./internal/core/marketplace/... ./internal/core/subscription/...
ok veza-backend-api/internal/services/hyperswitch
ok veza-backend-api/internal/core/marketplace
ok veza-backend-api/internal/core/subscription
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
c10d73da4e