feat(billing): add payment recovery and operations(Phase 7 Reconcile + Ops)

[law-chain-hot]

Summary

Adds the recovery and operations layer for Stripe-backed Billing. Webhooks remain the real-time path; PostgreSQL-backed reconciliation recovers setup and top-up rows when a provider response or webhook is lost.

Stripe webhook ────────────────┐
                               ▼
Pending setup/top-up ── due claim ── Stripe retrieve
                               │
                               ▼
                     row-locked idempotent apply
                               │
             ┌─────────────────┼──────────────────┐
             ▼                 ▼                  ▼
           Wallet       immutable ledger   provider event log
                                                    │
                                                    ▼
                                      retry queue + Admin health

What changed

• Reconciles pending Setup and Top-up attempts every minute with exponential backoff.
• Reuses stable local attempts, provider references, and Stripe idempotency keys.
• Persists failed normalized webhook application and retries it from PostgreSQL.
• Handles refund and dispute debits/restores with immutable adjustment transactions.
• Adds current/previous webhook signing secrets for controlled rotation.
• Adds Billing health alerts and Admin-only audited health/recovery endpoints.
• Adds a pre-deploy migration with recovery fields and indexes; no new tables.
• Adds release, rollback, secret rotation, alert, and incident runbook.

Recovery endpoints

• GET /admin/billing/health
• POST /admin/billing/reconcile
• POST /admin/billing/reconcile/top-up/:topUpId
• POST /admin/billing/reconcile/setup/:organizationId

Verification

• yarn test:billing:verify
  • API and migration: 77 passed
  • Stripe configuration: 11 passed
  • PostgreSQL edge cases: 11 passed
  • Dashboard: 39 passed
  • scoped ESLint, API build, Dashboard build passed
• Real Stripe test-mode browser E2E:
  • normal Setup + $5 Checkout + webhook: one credit
  • listener stopped after Setup: pending payment recovered from Stripe with one reconcile: event and one credit
  • real $5 refund: two provider notifications, one immutable -500 adjustment, final balance restored
• AWS_PROFILE=boxlite-sso aws sts get-caller-identity passed.

Scope boundary

This enables a monitored allow-listed beta. It does not block Box create/start or stop running resources at zero balance; prepaid enforcement remains a separate change.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: bd3312d9-d1d9-4a25-a6ca-17f2a7e093b6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/billing-v3-pr7-reconcile-ops

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}