# 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.