feat(Phase-5): Payments and webhook processing

[chitrank2050]

Overview

This is the tracking issue for Phase 5. The goal is to integrate a payment provider (Stripe), handle webhook events for payment lifecycle, and automate subscription renewals and payment failures.

Phase 4 generates invoices and tracks what tenants owe. Phase 5 collects the money.

Success Criteria

• Stripe payment intent created when invoice is finalized
• Webhook receiver validates Stripe signatures and processes events
• Webhook deduplication prevents double-processing
• Payment success automatically marks invoice as PAID + creates ledger PAYMENT
• Payment failure updates invoice status and triggers retry logic
• Subscription renewal on successful payment advances billing period
• Failed payment after max retries transitions subscription to PAST_DUE
• Tenant can view payment history and payment status via API
• Payment provider is abstracted behind an adapter interface (swappable)
• All payment mutations audit-logged

Tracking / Sub-tasks

• feat(payments): payment provider adapter interface + Stripe implementation #129
• feat(payments): schema for payment attempts and webhook events #130
• feat(payments): create payment intent on invoice finalize #131
• feat(payments): webhook receiver with signature validation and event routing #132
• feat(payments): webhook deduplication and idempotent processing #133
• feat(payments): payment success handler with ledger entry and period advancement #134
• feat(payments): payment failure handler with retry logic and PAST_DUE transition #135
• feat(payments): tenant-scoped payment history endpoints #136
• feat(seed): generate sample payment data for dev tenants #137
• docs(phase-5): finalize documentation and Bruno collection #138

Resources

• Architecture Log: docs/phases/phase-5.md (to be created)
• Architecture Doc: docs/architecture/phase-5-payments-webhooks.md (to be created)

Why this phase matters

Phase 4 generates invoices but relies on manual mark-paid calls. In production, payments are automated: Stripe charges the tenant's card, sends a webhook confirming success or failure, and the system updates accordingly. Without this, Meterplex is a billing calculator, not a billing system.

Webhook processing is the hardest integration pattern in SaaS: events arrive out of order, duplicates are common, signatures must be validated, and failures must be retried without double-charging. This phase handles all of it.

Note: This issue represents the "Phase 5" milestone. Individual PRs should reference the specific sub-tasks above.