salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8aef9c772753e91d2532692d2c44fd790ef8f976
igny8/docs/billing/billing-account-final-plan-2025-12-05.md
IGNY8 VPS (Salman) 4a16a6a402 Billing and account fixed - final
2025-12-05 12:56:24 +00:00

9.8 KiB
Raw Blame History

IGNY8 Billing & Account Platform — Final Plan

Date: 2025-12-05
Status: Canonical (supersedes all prior billing/account docs)
Scope: Tenant + Admin experience across Billing, Account, Credits, Payment Methods, and Payment Gateways. Frontend + Backend must use the IGNY8 standard API system.

1) Purpose & Principles

  • Single source of truth for billing/account flows.
  • One canonical API namespace per audience (tenant vs admin).
  • Align models ↔ services ↔ serializers ↔ frontend calls; remove drift.
  • Keep manual payment path healthy while Stripe/PayPal mature.
  • Favor incremental rollout with feature-flagged transitions.

2) Canonical Namespaces

  • Tenant: /api/v1/billing/...
  • Admin: /api/v1/admin/billing/...
  • Deprecate legacy /api/v1/admin/... (modules/billing) and duplicated routers. Optionally dual-serve for one release behind a feature flag.

3) Reality Snapshot (current code)

  • Tenant billing viewsets live in backend/igny8_core/business/billing/views.py (invoices, payments, credit packages, transactions).
  • Admin billing viewset also exists there (pending_payments, approvals, stats) but mounted at /api/v1/billing/admin/....
  • Legacy admin stack in backend/igny8_core/modules/billing/views.py exposes stats/users/credit-costs only; no invoices/payments.
  • Model drift: InvoiceService expects currency, tax_amount, total_amount that are absent on Invoice. PaymentService uses pending_approval/completed statuses not present in Payment.STATUS_CHOICES.
  • Frontend admin pages are wired but call nonexistent or legacy routes (e.g., /v1/admin/payments/).

4) Backend Plan

4.1 Models & Migrations (billing app)

  • Invoice: add currency, subtotal_amount, tax_amount, total_amount, line_items (JSON list), payment_method (string), stripe_invoice_id/paypal_invoice_id (nullable), metadata. Keep existing dates/status. Add index on status, created_at.
  • Payment: extend STATUS_CHOICES to include pending_approval, processing, completed, failed, refunded, cancelled. Add payment_method enum (stripe, paypal, bank_transfer, local_wallet, manual), gateway intent/charge ids, manual_reference, failure_reason, approved_by/at, metadata.
  • CreditPackage: ensure slug, price, credits, stripe_price_id exist and is_active, is_featured. Add sort_order for admin ordering.
  • PaymentMethodConfig: keep as source for country-level enablement; ensure uniqueness (country_code, payment_method).
  • Write forward/backward-safe migrations; backfill currency and totals with sensible defaults (e.g., USD, recompute total_amount=subtotal_amount+tax_amount where possible).

4.2 Services

  • InvoiceService: align fields; generate invoice numbers, compute subtotal/tax/total, store line items, mark paid/void/uncollectible, emit events, optionally render PDF stub.
  • PaymentService:
    • Stripe/PayPal: create intents/orders, store ids, update status on success/failure, attach to invoice, and trigger credit application when relevant.
    • Manual: create pending_approval, allow approve/reject endpoints to flip status and apply credits.
    • Sync helpers from webhooks/intents; emit structured logs.
  • SubscriptionService (existing): ensure plan ↔ subscription sync; use Stripe subscription id; update invoice/payment when Stripe posts events.
  • CreditPackageService: list active packages, create invoice + payment intent, on success add credits (CreditTransaction) and recalc balance.

4.3 Webhooks

  • Add /api/v1/billing/webhooks/stripe/ and /api/v1/billing/webhooks/paypal/ with signature verification.
  • Handle events: invoice.paid, invoice.payment_failed, customer.subscription.updated/deleted, payment_intent.succeeded/failed, PayPal equivalents.
  • Idempotent processing; log and surface dead-letter queue for failures.

4.4 APIs (Tenant)

  • GET /api/v1/billing/account_balance/ – balance + monthly included.
  • GET /api/v1/billing/transactions/ – credit transactions (paginated).
  • GET /api/v1/billing/usage/ – usage logs with filters.
  • GET /api/v1/billing/invoices/ | GET /api/v1/billing/invoices/:id/ | GET /api/v1/billing/invoices/:id/pdf/.
  • GET /api/v1/billing/payments/ | GET /api/v1/billing/payments/:id/.
  • GET /api/v1/billing/credit-packages/.
  • POST /api/v1/billing/credits/purchase/ – create intent; returns client secret + invoice id.
  • POST /api/v1/billing/subscriptions/create|upgrade|cancel/.
  • GET /api/v1/billing/subscriptions/ – current subscription status.
  • GET/POST /api/v1/billing/payment-methods/ – list/add; store tokens/ids, not card data.

4.5 APIs (Admin)

  • GET /api/v1/admin/billing/invoices/ | GET /:id/ – all accounts, filters (status, account, method, date), pagination, export.
  • GET /api/v1/admin/billing/payments/ | GET /:id/ – all accounts, filters (status, method, gateway).
  • POST /api/v1/admin/billing/payments/:id/approve/ | /reject/ – manual payments only.
  • GET/POST/PATCH/DELETE /api/v1/admin/billing/credit-packages/ – CRUD with is_featured, sort_order.
  • GET /api/v1/admin/billing/stats/ – totals, MRR, pending approvals, failed webhooks.
  • GET /api/v1/admin/billing/pending_payments/ – for approvals (same payload frontend expects).
  • AuthZ: developer/superuser only; enforce tenant scoping for non-admin routes.

4.6 Settings & Config

  • Add STRIPE_PUBLIC_KEY, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_WEBHOOK_ID to settings/env; feature-flag gateways.
  • Rate-limit payment endpoints; CSRF exempt webhooks only.

5) Frontend Plan

5.1 Service Layer (frontend/src/services/billing.api.ts)

  • Point all admin calls to /api/v1/admin/billing/...; remove dead /v1/admin/... routes.
  • Reuse tenant calls for user-facing pages; ensure response shapes match new serializers (InvoiceSerializer, PaymentSerializer, CreditPackageSerializer).
  • Add helpers for manual approval actions and credit-package CRUD.

5.2 Tenant Pages

  • Plans & Billing (/account/billing): tabs for Plan, Credits, Billing History (invoices), Payment Methods. Uses balance, subscription, invoices, payment-methods, credit-packages, purchase intent.
  • Purchase Credits (/account/credits/purchase): list packages → create purchase intent → confirm via Stripe/PayPal/manual upload → poll payment.
  • Invoices (/account/invoices): paginated table, filters, PDF download.
  • Payment Methods: list/add/remove default (via tokens).

5.3 Admin Pages

  • Billing Overview (/admin/billing): stats from /admin/billing/stats/, pending approvals summary.
  • Invoices (/admin/invoices): uses /admin/billing/invoices/; add filters (account, status, method, date) and CSV/PDF export.
  • Payments (/admin/payments): uses /admin/billing/payments/; add filters and status badges.
  • Credit Packages (/admin/credit-packages): CRUD via admin endpoints; show is_active, is_featured, sort_order, Stripe price id.
  • Payment Approvals (/admin/payments/approvals): call pending_payments, approve/reject endpoints; show invoice link and manual references.
  • Sidebar links already present—only fix data wiring.

5.4 UX/Consistency

  • Standard empty/error/loading states across billing pages.
  • Currency display from invoice/payment currency.
  • Role-guard tenant routes (owner/admin only for purchases; read-only for others where applicable).

6) Sequenced Action Plan

  • Day 0 (alignment): Merge this doc; add “retired” note to older docs; choose namespace flag (USE_NEW_ADMIN_BILLING_API=true).
  • Phase 1 (backend, 2-3 days): Migrate models; update services; add admin list endpoints; webhook stubs; tests for serializers and viewsets.
  • Phase 2 (gateways + frontend wiring, 3-4 days): Implement Stripe/PayPal intent paths, hook webhooks, wire billing.api.ts to new endpoints, fix admin pages, enable manual approvals end-to-end.
  • Phase 3 (polish, 2 days): Add exports, filters, pagination polish; observability (structured logs, alerts); finalize docs and remove legacy router.

7) Deliverables & DoD

  • Schema migration applied and reversible; services match models.
  • Canonical endpoints live and documented; legacy admin endpoints removed/flagged off.
  • Tenant billing pages load without 404s; purchases and subscriptions succeed (manual + Stripe at minimum).
  • Admin pages show data, support approvals, and package CRUD.
  • Tests: unit (services), API (tenant/admin billing), integration (purchase + manual approval flow), webhook idempotency.
  • Docs: this file referenced from legacy docs; endpoint matrix embedded in billing.api.ts JSDoc or a short /docs/billing/api-map.md.

8) Quick Endpoint Matrix (canonical)

  • Tenant: invoices (/api/v1/billing/invoices), payments (/api/v1/billing/payments), credit packages + purchase (/api/v1/billing/credit-packages, /credits/purchase), subscription create/upgrade/cancel (/subscriptions/...), payment methods (/payment-methods), usage/transactions/balance.
  • Admin: invoices (/api/v1/admin/billing/invoices), payments (/api/v1/admin/billing/payments), pending approvals (/api/v1/admin/billing/pending_payments), approve/reject (/api/v1/admin/billing/payments/:id/approve|reject), credit packages CRUD (/api/v1/admin/billing/credit-packages), stats (/api/v1/admin/billing/stats).

9) Rollout & Migration Notes

  • Run migrations during maintenance window; backfill currency/totals.
  • If dual-stack needed, proxy legacy admin routes to new handlers temporarily.
  • Communicate new admin endpoints to frontend before flipping flags.
  • Validate webhook secrets in non-prod before enabling in prod.

10) Retirement Notice

This document supersedes docs/working-docs/Original-plan-may-have-wrong-logic.md and docs/working-docs/admin-billing-plan-2025-12-05.md. Treat those as retired; keep only for historical reference.

Reference in New Issue View Git Blame Copy Permalink